3 ms·

I generally agree to comment with care. However the examples in the article are just bad. As a rule of thumb it is generally accepted that you comment your

I generally agree to comment with care. However the examples in the article are just bad. As a rule of thumb it is generally accepted that you comment your classes and public methods. You define the inputs and returns, and the general description of the stated purpose of the class/Method/Function. This is basis of your codebase and the available it's associated API. Code without comments is very bad. There is no such thing as self documenting code. You have to consider who will be making modifications to the code after you, and that your comments sole purpose is to convey the fundamental design of your code. document the purpose for the code, document the inputs and returns, document the algorithm steps when appropriate. Do not put a comment on every line. Just comment the unclear or potentially fuzzy bits. also on a side note, if your code is slick and clever and requires a comment to explain it because it is complex and cryptic. You Failed! Our life is frittered away by detail... simplify, simplify, simplify. --Henry David Thoreau

warlyware 9y ago
Thanks for your input on the article! In my my experience and research, it is very difficult to find "a rule of thumb [that] is generally accepted" regarding comments. While commenting on classes and public methods the way you describe is a common practice, my argument is that this is a largely arbitrary method of commenting code that can lead to comments that are not always maintained with the same care as the code it is describing. By only commenting when the code is not self explanatory, and cannot reasonably be refactored so as to make it self explanatory, your code will become easier to read and will be less prone to harboring unmaintained, misleading comments. And I couldn't agree more with your sentiment regarding code that is so "slick and clever" that it requires comments. Readability is better than slick and clever any day of the week.

warlyware 9y ago

Thanks for your input on the article! In my my experience and research, it is very difficult to find "a rule of thumb [that] is generally accepted" regarding comments. While commenting on classes and public methods the way you describe is a common practice, my argument is that this is a largely arbitrary method of commenting code that can lead to comments that are not always maintained with the same care as the code it is describing. By only commenting when the code is not self explanatory, and cannot reasonably be refactored so as to make it self explanatory, your code will become easier to read and will be less prone to harboring unmaintained, misleading comments. And I couldn't agree more with your sentiment regarding code that is so "slick and clever" that it requires comments. Readability is better than slick and clever any day of the week.