A primer on good code commenting
Code is great, but comments are better. If code is what tells a computer what to do, then comments are how you communicate your intent. If the logic for a function is very clearly communicated in the comments, it can be translated by another programmer into any other programming language. If a piece of code is well-commented throughout, then even without knowing all there is to know about the language or the rest of the classes being accessed at any given point, you can figure out what the code is doing. When you need to bring a new developer up to speed on your project, a huge factor in how quickly they’ll become useful is how well your project is commented.
I’m going to assume that you’re already familiar with how to create a comment, so this video is going to focus more on what and where to comment.
Probably the first and most important thing to comment are your functions and methods. These comments can significantly illuminate your API, and that can make it easier to find and re-use existing code or bring new developers up to speed.
PHP has an excellent support community dedicated to it, and out of that community came phpDocumentor – a handy free tool that will take your project and automatically generate an API for you. It will use your comments to flesh out that API, but only if you use a style of commenting known as “javadoc” or “doc-block”. Even without using this tool however, it’s a great convention to follow. Zend Studio, which I use for my own coding environment, automatically recognizes this style of comments and will assist in their creation.
The basic syntax of javadoc looks like this: {show prepared code segment with comment}
Notice that the first line contains a slash followed by 2 asterisks, and each line starts with an asterisk. The description of whatever is being commented is the first thing in the block. After that, you can use tags preceded by @ symbols to provide very specific information that programs such as phpDocumentor use.
There are a limited number of elements where phpDocumentor looks for and parses javadoc-style comments. I suggest you make a habit of placing these comments at the top of all of them. These include files, functions, defines and includes, as well as any global variables. And assuming your project is object-oriented, you should also place these comments above your class definitions, their methods, and their properties.
When documenting a function, as is the case here, your most important tags are ‘@param’ and ‘@return’. ‘@param’ tells the name and expected value type for each variable passed to the function (this information can also be gleaned to some extent from type-hinting, but not as broadly since as of PHP 5 type-hinting only includes null, array, and object types). ‘@return’ provides information about the type of value returned. In addition to those two, if your method can throw an exception, you should include a tag for ‘@throws’ for every type of exception your function might throw – the syntax is “@throws ExceptionType – conditions which will cause this exception to be thrown”.
Now in addition to those tags, javadoc officially recognizes many more. I won’t discuss all of them – there’s an exhaustive tutorial available online that I’ll point you to in a moment. But I will take you through the ones I find most helpful most often.
To reference another method elsewhere in your code, you can use ‘@see’. And in phpDocumentor this is really great, because if it recognizes what you’re linking to, it will actually create a hyperlink to the documentation of that other portion of your code. So for instance ‘@see GoToClass’ would create a link to the documentation for a class called ‘GoToClass’ if one exists in your project. And of course, it’s useful even if you don’t use phpDocumentor because it lets your reader know what other portions of the code use or are used by the thing you’re documenting.
When a project has lots of authors, it’s a very good idea to include a tag ‘@author’ in each of your contributions. Later, if someone has a question about how it works, they can see who wrote it and ask them to explain it.
At the beginning of each file, you can place a javadoc comment as well. In the automatically generated documentation, file or page-level comments have its own section. When you use it, you must include the ‘@package’ tag. The value in @package will specify a particular group of files that all relate to one another, and all appear within the navigation generated by the documentor for that package.
When you have to stop working on something before it’s finished, there’s a tag for that too. Use ‘@todo’ followed by a description of what still has to be written.
There are currently about 30 different tags recognized by phpDocumentor, and most other javadoc parsers will recognize them as well. You can learn about all of them by going to the phpdoc manual online.
Javadoc comments placed above your files, classes, functions, methods, and properties will really liven up your API if you generate one. And even if you don’t it’s going to make your code much easier to understand. But the other important places to comment are anytime you do something where simply looking at the code, it would be difficult to figure out what’s going on. As a general guide, if you call a function defined elsewhere, include a short comment about what that function should do. That way, the person trying to work on it doesn’t need to go and hunt down its definition in a separate file. The same is true if you invoke one of the more obscure PHP functions. And if you simply need to perform a task that requires some tricky logic, or is unlike the way things are done elsewhere in the project, write a short comment explaining what you did.
Personally, I find the best way to write my scripts is to start by outlining my logic within comments before I ever write my code. Then, I just place my code within the lines of logic where I’ve described what needs to happen. It helps me ensure my logic is good before I even start the actual coding, and when I’m done, I just leave the outline there for documentation.
December 08 2009 11:37 pm | Schmategories