Item 44: Write doc comments for all exposed API elements
The item does not even attempt to justify or explain it's reasoning. It just states that "If an API is to be usable, it must be documents". This is complete rubbish. A good Java developer can use and API by reading it!
It then the proceeds to make the frankly ludicrous statement "to write maintainable code, you should also write doc comments for most unexported classes, interfaces, constructors, methods and fields." The lack of maintainability of code is most of my problem with this item. Adding comments in the fashion simply duplicates what is already in the code, increasing the maintenance the code required. History dictates that developers are very good at updating and fixing code, but not the associated comments. Good code only has comments where it is necessary to say why and never how.
The item also states that "The doc comment for a method should describe succinctly the contract between the the method and its client." No! That's what the method name and signature should do.
In general, but not always, comments are a bad thing and should be used sparingly. The only time I can see doc comments being a good thing is if you're writing a library for someone else to use where you don't want them to have to look below the public interface.
The remainder of the item describes the details of how to write doc comments.
The item does not even attempt to justify or explain it's reasoning. It just states that "If an API is to be usable, it must be documents". This is complete rubbish. A good Java developer can use and API by reading it!
It then the proceeds to make the frankly ludicrous statement "to write maintainable code, you should also write doc comments for most unexported classes, interfaces, constructors, methods and fields." The lack of maintainability of code is most of my problem with this item. Adding comments in the fashion simply duplicates what is already in the code, increasing the maintenance the code required. History dictates that developers are very good at updating and fixing code, but not the associated comments. Good code only has comments where it is necessary to say why and never how.
The item also states that "The doc comment for a method should describe succinctly the contract between the the method and its client." No! That's what the method name and signature should do.
In general, but not always, comments are a bad thing and should be used sparingly. The only time I can see doc comments being a good thing is if you're writing a library for someone else to use where you don't want them to have to look below the public interface.
The remainder of the item describes the details of how to write doc comments.
Comments
Post a Comment