Spend any time around programmers, and at some point, one of them will opinionate that good code is self explanatory, and that documentation and comments are unnecessary - possibly evil. While every single other industry on the planet believes that undocumented machinations are dangerous, lazy programmers who misunderstand something they heard misquoted from some guys twitter account¹ are given airtime instead of being politely told to get their head examined.

For example - It’s highly tempting to believe that we don’t need to document the simple and obvious methods for getters and setters, because the code tells us what it does, especially if we use type hinting, such as in the example below.

<?php
class Article {
  public function setAuthor(User $user) {
    $this->author = $user;
  }
}

Isn’t that clear? The author is represented by a User object, and clearly you can pass any valid user to the setAuthor() method. Authors write articles, and by extension, can edit them. Obviously, making changes, a good programmer should be familiar with the implications of any changes they are making.

It’s a lovely theory, I’ll admit.

Now, imagine for a moment that it’s 5am in the morning. You are desperately trying to give a content editor the rights to edit an article to remove some text by 8am. If you do not, the company will literally be sued out of existence. The original programmer is on holiday and won’t be back till next Tuesday, and their backup just flat out isn’t answering the phone. You don’t know how any of this works, because you were literally hired last week.

With a bit of script magic, you figure out that you can call the above method with the content editors user object. The name on the article will be wrong for a while, but the text will can be updated, and corporate armageddon will be averted.

Except that it doesn’t work, because that’s not what the method does. Here’s the method with some real documentation.

<?php
class Article {
  /**
   * Sets the name that will be display in the author byline.
   *
   * @param User $user
   *   A user object with the fullname field populated.
   *
   * Note that this method only sets the name to be inserted into the
   *  byline, and has no effect on access rights.
   *
   * @see Article::addEditor() To give users content editing rights.
   */
  public function setAuthor(User $user) {
    $this->author = $user;
  }
}

For the lack of a few hundred well thought out bytes, the company could have been saved. But you’ll never know that, because by the time you found the method you were looking for, the lawyers were involved.

You’re better than that of course. Let’s assume assume that you found the right method first place. Now, how do you write the record out to the database?

If you’re lucky, our fictional Article class might extend from an ORM² class, in which case, there might be enough clues to work your way back up the stack and figure out how to make the changes stick. This is only a partial solution, because now you have to look through all the methods of the parent classes to work out how those work, and if the parent classes are written in the same lackadaisical style, you still have to work your way through the code of the ORM class. Wouldn’t it be nice if the original programmer had been nice enough to include that context in the original class?

<?php
/**
 * Basic article in memory class.
 *
 * More complex article types such as slide shows and blog posts should
 *  extend from this class.
 *
 * To load or write objects of this class from the database, use the
 *  the DbWidget\Article::load() & DbWidget\Article::save() methods.
 *
 * @see http://intranet.acmecorp.com/wiki/code/db-layer.html
 */
class Article {
    // Various methods here.
}

With very little effort, we know that this is an in-memory representation of the article, and therefore not an ORM type class. We know what methods we should be calling and where to find wider external documentation. What could have been several hours of discovery is now a few minutes of reading.

In an ideal world, programmers would thoroughly learn an entire codebase before doing anything with it. In reality, programmers seldom have the time or the inclination to go that deep. No matter how glaringly self-evident the code seemed at the time you wrote it, I can guarantee that at 4am, nothing is as obvious.

Further reading:

Up To Date - A fable about directions.