Disputed Code Comments vs. Self Describing Self Documenting Code
Last week I have been reviewing some implemented features on our product, it works fine but not well written, got to have some refactoring specially my rule on comments.
Perhaps this is one the most disputed practices in software development, code
comments. Personally, I seldom/don't comment my code. A well defined and
structured code with self-describing and self documenting names and declarations
is sufficient enough to make it understandable and maintainable at some point.
Task aware lines such as TODO, HACK, REVISE tags works well but not all times
unless it is integrated with the Issue Tracking tool or IDE. In some cases code
comments is a residue of pseudo-code and I suggest it be removed from release
code.
I have seen several cases where comments serve as documentation and
explanation of a plain and simple methods. It often comes to a point
that members of the team or API users are forced to read a bunch of comments
first before understand the program flow. Even experienced developers tried to
compensate their complex code, lacks of abstractness and intuitiveness, complex
class' responsibility, and lacks of refactoring by explaining how code works on
code comments.
Code comments also occupies a lot space on code view and added complexity if
not well written. A comment that says "//initialize the treeview with list
of products" on a method "InitializeProductTree(List<Product>
productList)" doesn't make sense!
Consistency of the comment to the intent of the code it describes is not
guaranteed. Developers that writes pseudo code first before implementing through
methods will likely forget to update the comments if a logic in code change and
thus code and comment becomes inconsistent and inaccurate.
Vanity. This is funny as I have seen some codes that serve as vanity and
aesthetics to show style. It looks beautiful seeing those green lines. Taking a
closer look and reading it, it tells me something. "I'm here, but you ain't
gonna need me".
XML documentation is best placed in a separate xml file so the code base size
will be reduced. A fully xml inline-documented class when not collapsed gives
complex view and forces the API user read the comments first.
When to put comments anyway?
I don't think there's general rule when and when not to place comments.
IMHO, its mainly common sense.
Intent. Comments describes the intent of the method or
class. It should tell why the code was written, at what feature or requirement
it serves.
Responsibility. Commends describes the responsibility of the
code and its participation in the implementation feature or fullfillment of a
requirement.
Guilty? Share your side.