Keeping Your PHP 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 / callable keywords 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. Just look at the image below and notice the lock icons next to the method names:

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 als

Truncated by Planet PHP, read more at the original (another 12413 bytes)

more