Do all the things like ++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatarSign Up
Code itself shouldn't need comments unless it is written badly. Comments should explain why the code is there and what it is supposed to achieve.
wowotek61631yCode don't need that kind of exaggerated comments that explains what it does every single line.
the Documentation only explains what the block of code (or maybe functions, lambda, etc) do and how to implements it
felbit4511yI myself almost never write comments since I found that they get out of date quickly and then I have two places I have to maintain. Most comments I write begin with "Refactor:" or "Todo:" and will not stay there for long.
But I do write extensive documentation where I explain in detail reasons and reasoning behind the code.
bnwbear1521yI’m a junior dev and senior devs would tell me “a good code doesn’t need comments” since it’s readable. It’s really true I did not have a hard time reading their code and they would usually put comments at the right places. Saves a lot of time (since no one needs to ask again and again) and looks really clean.
@Fast-Nop These 2 sentences contradict, to me. Sure, basic boilerplate code doesn't need comments if you're using reasonable function/variable names, which you should do. But I see way too much code doing bizarre things without explaining itself, and if you ask the developer why they'll say they think it's "self-documenting" -- even though nobody else can read it. I would rather see self-explanatory code with redundant comments than balls of mud with no comments at all. Too many programmers take it as a point of pride to not write comments because they think adding comments to their code is an admission that the code is bad.
@HollowKitty I'm no friend of a coding style where tons of stuff happen in one single line in convoluted expressions with ternary operators and side effects, and that's mostly what makes code hard to read.
The other thing is when clever optimisations break the obvious relationship to the problem domain, the code has to be explained. For example, when several operations on different logical variables are done at once by a set of bitwise operations on full integers.
But otherwise, the point is explaining what the code is trying to achieve in terms of goals because that also helps finding bugs in later code reviews: "You want to do this - but the code does something else?!"
Like, I won't explain that "line_ptr += 3;" goes three elementes further, that's obvious. But a useful comment here could be /* jump over the UTF-8 BOM */.