Content with Style

Web Technique

Comments on Comments

by Pascal Opitz on May 30 2006, 03:59

Introduction

The right kind of comments to speed up the development process and enable a couple of interesting possibilities to generate documentations automatically. This article tries to reflect on the pros and cons of comments and to show some interesting possibilities for automatic comment parsing.

Comment Basics

Comments are basically regions of written characters that don't get interpreted by the PHP parser. Instead they get stripped out, and they solely are functioning as meta data. So just in case you don't know about how to embed comments into your scripts I'll just give you a quick example. In PHP there is two ways of using comments:

// a single line comment is preceded by a double slash
/*
A multiline comment 
is enclosed by slashes
and asterisks
*/

This style of comments is used by many other languages like Java, JavaScript or ActionScript. You will find the comments in any documentation as one of the first things mentioned, so whatever language you use, adding comments will be no problem for you.

Reasons to comment your code

When I wrote the first drafts of what would become this article I basically reflected the traditional approach on comments: Comments are a good thing, comment your code, it will be more legible, external programmers will find it more easy to get into your code, etc. Interestingly this kicked off a little discussion about coding practices and about what happens when comments are getting out of sync. Obviously wrong comments are a huge problem, and there are some people that actually consider comments as completely redundant, if not even harmful, because they will be hard to maintain once the code gets changed and therefore misleading other developers afterwards.

This is quite an interesting point of view, and makes sense when the code is following naming conventions that are self explanatory and obvious, a state of coding that every coder should aim for.

On the other hand many people still feel the need for comments. Many feel that after a certain amount of time they can find their own thoughts being reflected in the comments more than in the raw code, and it helps them to quickly amend parts of the code without having to read it all.

Not sure what this conflict of beliefs would do to my article I did a little google research to find out more. I turns out that this discussion is not only going on within the CwS team, but all along the developers community (example), especially when it comes to extreme programming.

Pragmatic as I am I think I'll stick with what the PHP coding standards say:
“Comments should document decisions.”

This means that comments should be applied within the code once the code itself is not sufficient enough to explain why it does what it does. This also means comments within the code that are redundant should be avoided. As exceptions from the “avoid redundant comments” rule I would recommend anyone to use comments for Debugging, Gotchas and Automated Documentation, some applications that at the end of the discussion the members of CwS pretty much could agree on.

Comments and debugging

In the middle of development process commenting code to temporarily switching and and off whole blocks is extremely helpful. It avoids deleting parts of the scripts and then by accident (your application crashed, you forgot to save the file, etc) having to rewrite them because the undo function of your editor didn't get you anywhere.

It also is extremely helpful if you find little commented examples of the actual script usage within the script itself or if basic setting possibilities are just commented out so removing the comments enables the debugging mode, sends the emails to the test address or includes a different language library for example. People that ever edited the apache httpd.conf file know what I am talking about here and I think this is one of the most basic coding techniques to use.

Gotchas

Gotchas are embedded keywords that are used to point out potential issues or existing problems. Since they are quite easy to use with for example search and replace it is easy to quickly jump to all parts of the code marked with :TODO: or :BUG:.

An interesting aspect to gotchas is the possibility to have a robot finding them automatically. Good IDE's for example would be able to find gotchas and flag up every todo that has been marked as such. Again see the PHP coding standards for more on this.

Automated Documentation

One of the biggest benefits of doing your comments in a more sophisticated way is that it will enable you to use automated documentation tools. The most common tool for PHP is PHPDocumentator or PHPDoc which I found one of the most helpful tools ever. The PHPDoc application derived from JavaDoc and took over the same comment standards to extract html documentations out of the comments embedded into the PHP code.

The same commenting standard is used by other documentation tools like CcDoc or PHPXref and other applications like the Zend Studio IDE.

PHPDoc also can be installed as external tool in PHPEclipse and there is a variety of little plugins for other editors like VIM that will help you creating the PHPdoc style comments.

PHDoc in use

PHPDoc comments are very easy to apply and contain meta information embedded in PHPDoc tags. Let's have a look at a comment for a class and see how PHPDoc parses comments:

/**
  * short desc
  *
  * long desc
  * @package test
  * @author me
  * @version 1.0
  * @abstract
  * @copyright never
*/
class parclass
{
}   

As you can see the @ triggers the PHPDoc tags, and there are various tags that can apply depending on whether you document a function, a class or an include for example. At the end of the development process the comments and PHPDoc tags can be parsed into a complete HTML documentation that will give you a full overview of every class and function in your project. If you have done the comments right during the coding process your documentation will know all required parameters, all return types and the documentation will tell a story about how the classes and functions work.

To get an impression of how this looks like have a look on PHPDoc documenting itself.

XML comments in C#

Another common example of automatically generated documentation are the XML comments used in C#.

/// <summary>
/// This is the summary
/// </summary>
/// <param name="myParameter">The value passed</param>
public void MyMethod(string myParameter)
{
}

As you can see in the example above this works pretty similar to the JavaDoc/PHPDoc standard and offers a lot of flexibility by applying XSL templates to generate an HTML documentation.

IDE's like SharpDevelop or Visual Studio support this natively and provide code completion features for adding the comments to Classes and Methods.

Other uses for comments

Apart from the ones mentioned above, there might be various other possible applications for comments. The Wikipedia article on comments for example states that syntax highlighting could be one of them, and I can think of a coupe of CSS Hacks and various pieces of ASCII art.

Bottom line

While before writing this article I was clearly stating that comments are an essential addition to good coding style, the discussion about my first drafts made clear that I couldn't hold this up but needed to rethink my approach on how, when and why I was using comments. Quite an interesting lesson that was, and it showed once again that using your own head rather than a learned design/behavior/technique is actually a good thing.

That said it becomes obvious that it's necessary to find an approach that works for the individuals involved in the development process, and if you already have found your approach on commenting code and keeping it maintainable and up to date, then in my opinion there's no need for you to change it.

Personally I gained a lot since I started using generated documentations. Embedding the documentation into the source code in form of comments is probably the only way to make accurate documentations of big projects possible.

If I missed out any useful applications for comments feel free to post them in ... well ... the comments ;)

Comments

  • Nice article, but you forgot about the # comments

    by David on April 11 2006, 08:39 #

  • David: Thanks. I actually was thinking of leaving the example out. To mention every possible style of comments would be a bit of an overhead. For those who want an overview, check the Wikipedia article on Comments

    by Pascal Opitz on April 11 2006, 08:45 #

  • Pascal: Yeah, it’s just that the way you said it sounded like there were only two ways instead of three.

    by David on April 11 2006, 12:32 #

  • here is my comment toward the matter… I’m sorry if it has no value. (hey, at least i thought it was funny).

    by Dustin Diaz on April 11 2006, 01:00 #

  • Hi,

    I, as a C# developer, would add a short comment on C# code documentation.

    In Visual Studio.NET 2003 (.NET 1.1) only C# had this auto document feature. In the current release of Microsoft Visual Studio 2005 (.NET 2.0) C# and VB.NET both have that feature. Even in commenting you get IntelliSense to assist your documentation. There is even more (haven’t tried in VB.NET but i think it will work there to) if you start a XML comment in C# you type three slashes (///) and the IDE will automaticaly generate XML comments for all your parameters, etc. A really great feature.

    As long as the XML file created by the IDE is named the same as the assembly (DLL) it will show up for every developer that uses your dll.

    The most comon way to create a api documentation is to use a port of jDoc called nDoc: http://www.google.de/search?q=ndoc
    The result is really great.

    Everybody who want’s to testdrive this feature, there is a free download for the express versions of Visual Studio 2005:
    http://msdn.microsoft.com/vstudio/express/

    Very good article by the way…

    Ciao Marco

    by Marco on April 11 2006, 02:24 #

  • Dustin: I don’t think just because of that demonstration of your commenting practice you do count as Extreme Programmer. But funny it was :)

    Marco: One of the best features of Visual Studio is code completion, definitely. But for the record: SharpDevelop and MonoDevelop have code completion features, and other IDE's like the Zend Studio have similar features for PHP, even if these might be less sophisticated than in Visual Studio.

    Not sure about Eclipse and code completion for JavaDoc comments ... Has anyone used Kommodo yet? How is it with that one?

    by Pascal Opitz on April 11 2006, 03:28 #

  • You should read up on Litterate Programming by Donad Knuth… ;)
    Written in the mid 60s it was a pretty foresightful statement…

    by Thomas Hansen on January 18 2007, 12:46 #

  • this article is a good one.some more examples like different styles of commenting could have been given.

    by arun d vannia on January 25 2007, 04:47 #

  • Pascal,
    Thanks for the link to the Wikipedia article!

    by Richard Salzman on May 8 2007, 19:28 #