Bitesize – Comments

I like to encourage programming best-practices where possible. I also would like to encourage discussion about what is good programming practice. What might seem obvious to some may be completely new to others. I also find that there is very little in the way of advice on how best to program, especially for our more inexperienced comrades. Besides, you are never to old to learn.

As such, I am going to start by offering small pieces of advice, mostly related to Java but much can be considered good practice for any programming language. You may find that you disagree with what I have to say. If so, great!! Feel free to share your opinions.

The first topic of discussion are comments. This might seem like a very trivial topic but I can assure you it is one of the most important for programmers but is sadly the most often abused.

First of all, the best form of documentation is the code itself. Therefore, when writing code, do so in a way that makes the code readable to other developers. The following series of tips aim to try to make your code more readable:

• Try to avoid unnecessarily clever or cryptic statements. These are usually no faster when compiled and optimised by your Java compiler. At the very least, use a comment to explain what you have done and why you have done it this way,
• Try to use short, meaningful names for classes/methods/variables except for throwaway variables such as loop counters. Cryptically abbreviated names provide little or no benefit other than saving a few extra key types (even less so with IDE word completion support).
• Be consistent in your use of white space. If you are modifying an existing class, it may make more sense to adopt its use of white space to avoid untidy looking code with a mixture of different styles.
• Avoid unnecessarily long classes and methods. A large class or method suggests that it may be overly complex, doing several different (albeit related) tasks. It may be that it could be broken up into several smaller, more meaningful and therefore easier to understand classes or methods.

JavaDoc comments (/** java doc comment */) are used by the JavaDoc utility to automatically generate API Documentation for your code. You should use these to describe the public API of your class or interface to the outside world. This should include an overview of the class or interface, possibly including a simple use case. Sun provide a useful guide to writing JavaDoc comments. JavaDoc is particularly important if you are developing an API to be given to 3^rd party developers (including your colleagues).

Normal Java comments are used to describe internal methods and blocks of code (/* multi-line comment */ and // single line comment).

Finally, it is possible to embed special task based comments such as FIXME and TODO that can provide instructions to yourself or other developers and may be supported by IDEs such as Eclipse. These should be removed before an application is released into production.

It is not recommended that developers use comments to disable code, with the intention that if it is needed subsequently then it can be easily uncommented. The unwanted code should be removed and then committed to your source control system will a meaningful comment. It is the source controls system’s job to maintain old versions of code and to make it available if needed again in the future. Blocks of commented out code clutter a class and can make it more difficult for developers to maintain in the future.