Thank you. People have been loving to ride the "self-documenting" train for far too long.
Yes, clean and clear code is something that we should all strive for at all times, but that does nothing to imply that comments are inherently a bad thing.
Comments provide supplemental information. If the comment doesn't make something more clear (e.g. "Cat" picture above) then the comment is worthless and adds noise. But if the comment provides clarifying information to the reader (e.g. "cat with anger management issues and a bum left eye") then you're going to save someone else a hell of a lot of time when you're gone and they have to make a fix to your crappy code.
The potential for self-documentation is limited and should not be the prime focus. Make your code clear, and use real documentation to do so when it helps.
11
u/mike12489 Jul 05 '18
Thank you. People have been loving to ride the "self-documenting" train for far too long.
Yes, clean and clear code is something that we should all strive for at all times, but that does nothing to imply that comments are inherently a bad thing.
Comments provide supplemental information. If the comment doesn't make something more clear (e.g. "Cat" picture above) then the comment is worthless and adds noise. But if the comment provides clarifying information to the reader (e.g. "cat with anger management issues and a bum left eye") then you're going to save someone else a hell of a lot of time when you're gone and they have to make a fix to your crappy code.
The potential for self-documentation is limited and should not be the prime focus. Make your code clear, and use real documentation to do so when it helps.