3 ms·
Stop Commenting Your Code, Please.
- mkelly 17y agoThe types of comments I've found useful are ones that explain "why". Either summarizing a function or class at a high level (why I should use this thing, why it exists), or explaining a single line iff it's highly counter-intuitive. e.g., "This is a Foo to replace the broken one in the Bar library, which doesn't frotz Baz correctly." "Yes, we actually have to do this because Qux isn't in magic mode yet." I figure a comment is worth it if it's highly likely to save someone from ripping out/changing a section just to see why it's done that way (which is sometimes a fun exercise, but mostly just reminds you of some subtle detail you forgot).
- thismat 17y agoA friend of mine always says "Your code should explain what it does, comments should explain why.". I agree with with you and him completely.
- windsurfer 17y agoSometimes I like seeing comments explaining what a complex statement does, too.
- wglb 17y agoAfter reading "Refactoring" by Martin Fowler, I would say "comments are bugs". I still operate that way, excepting a one-line description of a function or class. In rare situations, a longer explanation of convoluted code is called for. Yes, I am still trying to reconcile this with "Literate Programming", unsuccessfully.