Keep Your Code Well Documented
Introduction
Pretty much every PHP developer writes comments along with the actual code. But the language itself doesn’t impose any rules on how to do so. You just have to wrap them around some specific tags and then you can write any content you want. So what exactly should be put in the comment blocks to keep them useful? Which parts of the code should be documented and which shouldn’t? In this article I will present some important rules which may help you in keeping your PHP code well documented and understandable.
1. Write code that explains itself
First and foremost, the code you write may serve as a good piece of documentation even without adding a single comment block to it. While transforming the logic into pieces of code you can do a lot to make the code clear. Here are just a few examples:
Variable, function and class naming
As you can name your pieces of code in almost any way you want, you can use it as your advantage in terms of keeping the code understandable. Just remember to choose clear names, not to make up any strange abbreviations or use names that may be ambiguous. If your variable represents an instance of a VeryImportantCustomer class, just call it $veryImportantCustomer, not $customer, $vimpCust or$tempcustomer. Don’t be afraid of making typos in longer names as your IDE will probably warn you about unused variables or other inconsistencies in your code. I’m sure that using proper naming will help a lot in figuring out what’s going on in your code. It’s a simple rule but it may be easily forgotten in your everyday work.
Type hinting
PHP allows you to put class/interface names or array/ callablekeywords next to a function parameter. It prevents you from making wrong function calls but it also serves as an important piece of information for anyone reading your code. You don’t have to examine the function body to get to know how to call the function. You can also quickly check how the different functions and classes can pass values between each other. And remember that your IDE will probably interpret the type hints and use them to describe the functions in popups or hints which are being displayed while you’re working.
Method visibility
Another concept worth mentioning is the method visibility. Assigning proper visibility to class methods is said to be an important part of writing quality object-oriented code. On one hand, it shows which code represents the part of the logic that should stay inside the class and shouldn’t be revealed to other classes in the application. On the other, it exposes certain class methods to public access so they can be called from outside the class and communicate with other parts of the application.
If you write code that includes setting proper method visibility, other developers will quickly figure out how to work with the class you’ve developed. They will see that there are a few public methods that they can refer to in their code. They will also notice which parts of the logic that you wrote are left to be handled by private class methods and probably shouldn’t be touched.
Again, such hints are also being interpreted by your IDE. The editor you use can probably show you a list of class methods, along with their visibility.
2. Keep the balance
Of course you may feel that the code itself is not always clear enough and needs additional explanation. It is especially true when you’re implementing a complicated part of the business logic, performing complex calculations or just using commands that are difficult to understand at first sight (like regular expression patterns, array transformations etc.). In such cases writing a short comment will certainly help in getting to know what’s going on.
On the other hand, comment blocks shouldn’t make up for poorly written code. If your code contains too many loops or control structures and even you don’t know how it works without analyzing it for a couple of minutes, leaving it like that with a few comment lines isn’t the best solution. You should rather put some effort in refactoring the code instead of trying to explain it in comments.
Aside from complex code blocks, there are also such parts of code that are clear and do not represent any complicated logic. Some developers tend to put comment blocks even for these parts of their apps, which is unnecessary in my opinion.
3. Remember about the doc blocks
As you can see in the code examples above, some comment blocks contain specific keywords beginning with the @ character. I used @var to describe the type of a class property and @param to inform about the method parameter type. You can also use @return tag which informs about the type of the value being returned by a function. Other tags may be employed to describe some general info about the application or its part (like the author, the package, the type of licence).
Doc blocks tags contain information that cannot be included in the code itself. Specifying the type of class properties or function return values is especially helpful as it can be parsed by most of the IDEs and shown in hints. Of course you can also insert a custom text in a doc block which will serve as a function or class documentation. It may be especially important if your project needs to have its documentation available from outside the code. In such cases you can make use of the apps that analyze the doc blocks and generate the documentation of the whole application basing on their content.
If the code is easy to understand and I don’t need to produce an extended documentation, I just keep the tags that provide the information about the variable types and return values.
Summary
In this article I presented some tips on how to maintain the code documentation in a PHP application. I think comments aren’t necessary if you produce code which is clear and just explains itself. The proper place to put comments is when you implement some complex logic or use commands that are just not very readable for a human. It is also worth remembering to insert doc block tags which describe variable types or function return values as such information cannot be included in the code itself. If you need to maintain more detailed project documentation, also put appropriate descriptions in doc blocks.