in Best Practices, Clean Code, PHP

Documenting your code in a useful way

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:

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).

Frustrated with your company’s development practices?

You don't have to be!

No matter what the issues are, they can be fixed. You can begin to shed light on these issues with my handy checklist.

Plus, I'll help you with strategies to approach the issues at the organization level and "punch above your weight."

Powered by ConvertKit