Best practices in comment writing and documentation

Question

Commenting nowadays is easier than ever. In Java, there are some nice techniques for linking comments to classes, and Java IDEs are good at making comment shells for you. Languages like Clojure even allow you to add a description of a function in the function code itself as an argument.

However we still live in an age where there are often obsolete or poor comments written by good developers - I'm interested in improving the robustness and usefulness of my comments.

In particular I'm interested in Java/Clojure/Python here, but answers don't need be language-specific.

Are there any emerging techniques that validate comments and automatically detect either "flimsy" comments (for example comments with magic numbers, incomplete sentences, etc..) or incorrect comments (for example, detecting mispelled variables or the like).

And more importantly: Are there accepted "commenting-policies" or strategies out there? There is plenty of advice out there on how to code - but what about "how to comment?"

Answer 1

• Names/documentation should tell you what you are doing.

• Implementation should tell you how you are doing it.

• Comments should tell you why you do it the way you do.

Answer 2

This might be controversial, but my advice would be to write as FEW comments as possible. Use nice, clear class names, variable names and method names instead. Write your code in the clearest way that you can; and consider this to be the most important attribute of your code (other than that it meets its requirements). Only write a comment if you've made a method as clear as you possibly can, and you still think it requires further explanation.

And have an organisational practice, that whenever anyone changes a class in any way, they have to make sure the comments are still all correct.

Answer 3

I'm not sure about other languages, but python allows you to write doctests which are a form of self-validating comments. Of course, they shouldn't be used in place of real unit testing, but are a quick and easy method of documenting specific functions that may not be as obvious as they should be. They come with the added benefit of being able to execute the comment tests to verify that comments are still correct (at least the portion of them that contain tests).

Answer 4

One of the most authoritative location to find how to use code comment to generate documentation automatically is surely doxygen. Though there could me more of such tools.

This defines the standard of comment writing which should be followed to automatically generate documentation. However, this gives more of a structure but doesn't validate semantically; for example it can't check if you have used misleading english to describe the purpose of a function!

While, this is the best thing that make comments structured, personally i feel there is more documentation needed to make code more maintainable as such. Some time back there was a question in P.SE Can code be the documentation in open source developer tools? How frequently is it? Of course, This applies to non-open-source projects as well.

To make code more maintainable - it is practically more important that there exists a external documentation that helps create structure of how to treat code, and then comments inside the code should be restricted to see

I think, if you want to define the policies for comment writing you should include as a holistic approach included in the coding standard. See this: What could be some pitfalls in introducing a style guide and documentation generating software in a development team?

Usually a comments constitutes less than 5% of the code. And in practice while code-reviews itself draws much less attentions (over other aspects of development) is is practically difficult that comments are also reviewed.

Answer 5

Are there any emerging techniques that validate comments and automatically detect either "flimsy" comments (for example comments with magic numbers, incomplete sentences, etc..) or incorrect comments (for example, detecting mispelled variables or the like).

There is a well-know technique - it is called "code-review", and has a sister named "pair-programming". Don't expect anything "automagically" here.

And more importantly : Are there accepted "commenting-policies" or strategies out there ? There is plenty of advice out there on how to code --- but what about "how to comment?"

"Code complete" contains not only all about how to code, but also chapters on "how to comment", especially on how to write self-documenting code.

Answer 6

Specific to Java one source I've enjoyed is Oracle's How to Write Doc Comments for the Javadoc Tool:

This document describes the style guide, tag and image conventions we use in documentation comments for Java programs written at Java Software, Sun Microsystems.

And Item 44: Write doc comments for all exposed API elements:

If an API is to be usable, it must be documented. Traditionally API documentation was generated manually, and keeping it in sync with code was a chore. The Java programming environment eases this task with the Javadoc utility. Javadoc generates API documentation automatically from source code with specially formatted documentation comments, more commonly known as doc comments.

from Effective Java 2nd Edition.