Adding code comments is supposed to be good practice, but here is why it often fails:
- Code is the single authoritative source of truth in a program!
- There is no way to ensure that code comments are correct at all times (not always updated as code changes).
- Comments are written in human language which can be prone to misinterpretation.
First put your good intentions into writing simple and readable code.
Write self descriptive code ! Your code should be read like sentences. Avoid smart shortcuts and tricks because they break the reading. Expect the reader to have solid programming knowledge but no knowledge about the purpose of your code. If code is too compact add extra code steps to document it, for example:
...
final Person dummyPerson = new Person("Joe", "Bloggs");
return dummyPerson;
Instead of using a comment:
...
// Return dummy person.
return new Person("Joe", "Blogs");
Ok ok, this example was a bit silly but you got the idea.
Using long names is considered bad practice, I disagree. Prefer using long explicit names over short meaningless names which require code comments. Sometimes long names are really annoying, for example when they keep appearing everywhere in some algorithm, in that case you could use a comment.
Consider using more columns:
The default max of 80 columns is terrible, use a wide screen and use 120 columns or more, the code will be more readable because long lines will not wrap anymore and you can use longer more explicit names.
Use assertions to document pre and post conditions instead of lengthy comments.
public List<String> listFiles(final String folderUrl) {
assert folderUrl!= null;
assert folderUrl.endsWith("/");
...
}
If you write an API a good documentation is necessary but for internal code I think comments should not replace good naming and code clarity. I use code comments when the code is not really self documenting. Comments should convey what code cannot. They should explain the reasons for a specific design decision, they should explain what code is supposed to achieve and why.
Learn how to use the Javadoc, it not only looks better, it can also help automatically update some documentation. When referring to code try using the link tag. Your IDE may automatically update the linked method and class names during renaming which ensures that some of your documentation stays up to date.
/**
* Use the link tag: {@link SomeClass#someMethod}
*/
Links:
I totally agree. However, instead of using assertions I’d rather use JSR 305 Annotations like @Nonnull, @Nonnegative, @Nullable etc. Those can be placed on parameters and return values and help to further describe an API. Also it is not only visible to the programmer but also to the IDE so good ones like IntelliJ can perform static analysis and provide actual warnings or errors based on the given constraints.
Actually, it’s not “instead” – use both: Annotations where possible and assertions to check complex constraints.
Hello Andreas,
I now heavily use those annotations along with FindBugs but at the time I wrote the article (2011) I did not know about them.
It would be nice if you could comment on the original article on my blog.
Now I use both assertions and those annotations.
Oops,
JavaCodeGeeks sold it as new content on google+ therefore I didn’t check the date ;-)