Re:Your Code is Not Self Documenting
by mech4bg on Sunday January 09, 2011 @11:44PM
(#2087510)
I like Google's viewpoint on this... "incorrect documentation is a bug, and should be fixed." Complaining about the code diverging from the comments therefore comments are worthless is silly imo.
While documentation should not be over the top and code should be readable, I am sick of seeing completely uncommented functions that are non-obvious. There is a happy medium of having easy to read and well styled code and accompanying documentation that explains any gotchas and difficult sections. Sometimes just a written out purpose for the function can be surprisingly useful.
If you've worked in a company with a large shared codebase, you learn to love good comments.
While documentation should not be over the top and code should be readable, I am sick of seeing completely uncommented functions that are non-obvious. There is a happy medium of having easy to read and well styled code and accompanying documentation that explains any gotchas and difficult sections. Sometimes just a written out purpose for the function can be surprisingly useful.
If you've worked in a company with a large shared codebase, you learn to love good comments.