Below are my Do's and Don'ts on code commenting. - B. Lawler
Don't use comments to track author, revision, and related configuration management information - use your configuration management tools instead. Putting comments like “Author: John Smith” or “Revision: 2.3” as comments in the code is an antiquated method for handling this information - what about files that have multiple authors, how to you track revisions to image files, etc. This is much more appropriately done using configuration management tools.
Don't use comments to define the code - write clearer, more English-like, code instead. In any modern language, using any modern compiler, there is no advantage to using the variable “X” instead of using “AccountHoldersCurrentBalance”. Spend the extra keystrokes on a properly defined variable instead of a comment that says “X is the account holder's current balance”. Any comment of this type longer than a sentence or so indicates either that the code is poorly formed or that you are burying in code information that should be more visible (see next comment).
Don't bury in the code comments any information that needs to be known to people other than programmers - use the system documentation. It is fine to put in the code information that applies only to the software developers - they read code and will find this information when they do. Any information that should be part of the broader understanding of the system (e.g. adherence to security policies, computation of interest, etc.) should be in the public view.
Don't put requirements in the code - use the requirements management tools and trace those requirements to code components. The surest way to a wrecked system is for there to be multiple versions of a requirement - e.g. one in the document the business analysts read and another in the code the programmers are working on. Modern development tools make it pretty painless to capture even detailed requirements in CASE tools and to trace them to code components - this is a much better practice.
Don't put information in code that is better captured in analysis/design model. One of the problems with putting information about a business process in code is that these descriptions usually get chopped up to fit into the code blocks (usually files) supported by a language - explanations of the business logic that spans large code blocks is awkward embedded in code (and needs to be seen by other people). A better solution is to use modeling tools (e.g. UML tools like Rose or Together) that can keep code blocks and diagrams associated together.
Do use comments to explain peculiar syntax of statements. For example, when the current use of a language includes some conflicts in sytax - e.g. Microsoft Visual C++ versus ANSI C++. These style decisions and dependencies must be documented in the system documentation (and diagrams) but in-line comments can help clarify the syntax of key statements.
Do use comments to explain any convoluted algorithms. Anticipate how a maintenance programmer would read your code - the assumptions they might make, dead-ends in ways to solve the problem, etc. If that future programmer is likely to wonder “Why isn't this done like....”, that was something you tried, and there is a legitimate reason it didn't work - this is a good thing to explain.