Re:Your Code is Not Self Documenting
by j_baker on Sunday January 09, 2011 @09:29PM
(#2087197)
I grant that all code can't be self documenting. But you don't commit suicide just because you're going to die at some point anyway. Instead, you try to make your life as long and happy as possible.
Your highest priority should be to make your code self-documenting as possible, even though that isn't always possible.
That said, the author does have a valid point in that public APIs do need documentation. But I wouldn't go so far as to say that every method (private or not) needs documenting. Unnecessary comments and documentation should be treated like any other kind of useless code. They should be removed.
Your highest priority should be to make your code self-documenting as possible, even though that isn't always possible.
That said, the author does have a valid point in that public APIs do need documentation. But I wouldn't go so far as to say that every method (private or not) needs documenting. Unnecessary comments and documentation should be treated like any other kind of useless code. They should be removed.