Documenting your code in a useful way

« The definitive guide to contributing to open source

Few things bring out fights among programmers quite like a fight over documentation. There are many schools of thought, from “document every line” to “let the code self-document.” For the most part, PHP seems to have agreed on a generalized standard for documentation in code, called PHPDoc. Actual blocks of documentation are referred to as “Docblocks”*.

But within PHPDoc, there are many different styles and behaviors. And so, I have developed what I consider to be my “best tips” for documenting your code with Docblocks.

What is a Docblock

Ah, yes. Before we dive in, let me explain what a Docblock actually is.

A “Docblock” is a special code comment that offers an explanation of the purpose, arguments, return values and throw exceptions for a block of code.

<?php

/**
 * Some description of the function can go here.
 * 
 * @param mixed $abc
 * @param array $def
 * @param stdClass|null $ehi
 * @return bool
 * @throws \Exception
 */
 function testFunc($abc, array $def = array(), stdClass $ehi = null) {
     // Code goes here
 }

The PHP-FIG is working on a standard (PSR-5) for Docblock that all PHP developers can use. This standard is current in draft, but it offers a good first look at the thinking within the PHP community.

Document “structural elements” of your code

It’s important that you take the time to document the structural elements of your code with a Docblock, so that developers coming after you will be able to follow along.

“Structural elements” include classes, functions, methods and properties. Flow control devices like loops are not included.

Modern IDEs like PHPStorm automatically produce the Docblock from the function signature. All you have to do is start typing the Docblock and the IDE will auto-populate all the information it can figure out. Of course, the IDE is not perfect; it can’t know, for example, that you want an integer instead of a string; however, it will (as best it can) determine the types of objects passed in as well as other behaviors from the function itself.

PHPStorm is also configured to use Docblocks to offer code hints, so make sure your Docblocks get updated as your methods and functions do!

Provide a description along with your Docblock

Recently, my friend Larry Garfield posted this on Twitter:

If your docblock doesn't offer more information than is available from reading the func signature, you are just wasting my time. #RealDocs

— Larry Garfield (@Crell) December 1, 2014

Larry has a point. A Docblock that offers up the function arguments might “pass review”, but they aren’t going to offer you much in the way of useful information later on.

Docblocks support adding a description of the control structure you’re documenting. It should be the first few lines of the Docblock. I personally like a blank line between the description and the function arguments, but it’s up to you.

Telling me what the function or method does is just as important as telling me what the expected argument types are. It helps me know whether to use Class:a() or Class:b() for a particular given task.

Document your internal API, too.

You might think that protected and private functions don’t need Docblocks, or don’t need a full description. But that kind of thinking is mistaken. The internal API needs documentation, too.

Why? Because in six months when you come back to your code, you’re going to need to change something in the internal API, and without the Docblocks you won’t remember what you were intending. In addition, your internal API is subject to extension by subclasses, and you may well need to read through the documentation to know excatly where you want to make your changes.

Write documentation that you can understand.

When you write your documentation, make sure you give it a once-over for clarity. You’d be amazed at how many Docblock comments read “Calling the function that does the thing.” Okay, perhaps not that bad, but close. Read your comment, through the lens of someone who has never ever seen this code before. Does it make sense?

Remember, the person you’re writing documentation for very well may be you six months from today.

The actual standard for a “Docblock” is more complex than this, but for simplicity, we’ll stick with this definition. For a more complete description, see PSR-5 (in draft at time of writing).

Brandon Savage is the author of Mastering Object Oriented PHP and Practical Design Patterns in PHP

Posted on 12/11/2014 at 8:00 am
Categories: Best Practices, PHP, Clean Code

There are currently no comments.