Comments

Nothing can be quite so helpful as a well-placed comment.Nothing can clutter up a module more than frivolous dogmatic comments.Nothing can be quite so damaging as an old crufry comment that propages lies and misinformation.

The proper use of comments is to compensate for our failure to express ourself in code.Comments are always failures.We must have them because we cannot always figure out how to express ourselves without them,but their ues is not a cause for celebration.

Comments do not make up for bad code

　　One of the more common motivations for writing comments is bad code.Clear and expressive code with few comments is far superior to cluttered and complex code with lots of comments.Rather than spend your time wrting the comments that explain the mess you've made, spend it cleaning that mess.

Explain yourself in code

　　There are certainly times when code makes a poor vehicle for explanation.In many cases it's simply a matter of creating a function that says the same thing as the comment you want to write.

Good comments

　　Legal Comments

　　　　Sometimes our corporate coding standards force us to write certain comments for legal reasons.For example, copyright and authorship statements are necessary and reasonable things to put into a comment at the start of each source file.Comments like this should not be contracts or legal tomes.Where possible,refer to a standard license or other external document rather than putting all the terms and conditions into the comment.

　　Informative Comments

　　　　It is sometimes useful to provide basic information with a comment.For example, consider this comment that explains the value of an abtract methos:

　　　　// Returns an instance of the Responder being tested

　　　　protected abstract Responder reponderInstance();

　　　　A comment like this sometimes be useful, but it is better to use the name of the function to convey the information where possible.For example, in this case the comment could be made redundant by renaming the function:responderBeingTested.

　　Explanation of Intent

　　　　Sometimes a comment goes beyond just useful information about the implementation and provides the intent behind a decision.

　　Clarification

　　　　Sometimes it is just helpful to translate the meaning of some obscure argument or return value into something that's readable.In general it is better to find a way to make that argument or return value clear in its own right;but when its part of the standard library, or in code that you cannot alter, then a helpful clarifying comment can be useful.

　　Warning of Consequences

　　　　Sometimes it is useful to warn other programmers about certain consequences.Nowadays, of course, we'd turn off the best cast by using the @Ignore attribute with an appropriate explanatory string.But back in the days before JUnit 4, putting an underscore in front of the method name was a common convention.

　　TODO Comments

　　　　It is sometimes reasonable to leave "To do" notes in the form of //TODO comments.

　　　　TODO are jobs that the programmer thinks should be done, but for some reason can't do at the moment.It might be a reminder to delete a deprecated feature or a plea for someone else to look at a problem.It might be a request for someone else to think of a better name or a reminder to make a change that is dependent on a planned event.Whatever else a TODO  might be, it is not an excuse to leave bad code in the system.

　　Amplification

　　　　A comment may be used to amplify the importance of something that may otherwise seem inconsequential.

　　Javadocs in Public APIs

　　　　There is nothing quite so helpful and satisfying as a well-described public API.The javadocs for the standard Java library are a case in point.It woulde be difficult,a t best, to write Java programs without them.

　　　　If your are writing a public API, then you should certainly write good javadocs for it.

Bad Comments

　　Mumbling

　　　　Plopping in a comment just because you feel you should or because the process requires it, is a hack.If you decide to write a comment,then spend the time necessary to make sure it is the best commetn you can write.

　　　　Our only recourse is to examine the code in other parts of the system to find out what's going on.Any comment that forces you to look in another module for the meaning of that comment has failed to communicate to you and is not worth the bits it consumes.

　　Redundant Comments

　　　　The comment certainly not more informative than the code.It dose not justify the code, or provide intent or rationale.It is not easier to read than the code.Indeed, it is less precise than the code and entices the reader to accept the lack of precision in lieu of true understanding.

　　Misleading Comments

　　　　Sometimes, with all the best intentions, a programmer makes a statement in his comments that isn't precise enough to be accurate.

　　Mandated Comments

　　　　It is just plain silly to have a rule that every function must hava a javadoc, or every variable must have a comment.Comments like this just clutter up the code,propagate lies and lend to general confusion and disorganization.

　　Journal Comments

　　　　Sometimes people add a comment to the start of a module every time they edit it.These comments accumulate as a kind of journal or log,of every change that has ever been made.　　

　　Noise Comments

　　Scary Noise

　　Don't use a comment when you can use a function or a variable

　　　　The author of the original code may have written the comment first and then written the code to fulfill the comment.However, the author should then have refactored the code , as I did, so that the comment shoule be removed.

　　Position Markers

　　　　Sometimes programmers like to mark a particular position in a source file.There are rare times when it makes sense to gather certain functions together beneath a banner like this.But in general they are clutter that should be eliminated.A banner is startling and obvious if you don't see banners very often.So use them very sparingly, and only when the benefit is significant.

　　Closing Brace Comments

　　　　Sometimes programmers will put special comments on closing braces.Although this might make sense for long functions with deeplu nested structures,it serves only to clutter the kind of small and encapsulated functions that we prefer.So if you find yourself wanting to mark your closing braces, try to shorten your functions instead.

　　Attributions and bylines

　　　　Source code control systems are very good at remembering who added what,when.There is no need to pollute the code with little by lines.You might think that such comments would be useful in order to help others know who to talk to about the code.But the reality is that they tend to stay around for years and years, getting less and less accurate and relevant.Again,the source code control system is a better place for this kind of information.

　　Commented-Out Code

　　　　Few practices are as odious as commenting-out code.Don't do this.Others who see that commented-out codd won't have the courage to delete it.They'll think it is there for a reason and is too important to delete.

　　HTML Comments

　　　　HTML in source code comments is an abomination, as you can tell by reading the code below.It makes the comments hard to read in the one place where they should be easy to read - the editor/IDE.

　　Nonlocal Information

　　　　If you must write a comment, then make sure it describes the code it appears near.Don't offer systemwide information in the context of a local comment.

　　Too Much Information

　　　　Don't put interesting historical discussions or irrelevant descriptions of details into your comments.

　　Inobvious Connection

　　　　The connection between a comment and the code it describes should be obvious.If you are going to the trouble to write a comment, then at least you'd like the reader to be able to look at the comment and the code and understand what the comment is talking about.

　　Function Headers

　　　　Short functions don't need much description.A well-chosen name for a small function that does one thing is ususally better than a comment header.

　　Javadocs in Nonpublic Code

　　　　As useful as javadocs are for public APIs, they are anathema to code that is not intended for public comsumption.