Do you agree?

Junior: What are comments

Mid-level: Hah! My code is so clean, I don't NEED comments!

Senior: comments comments comments comments comments comments comments comments comments comments comments comments comme-...

My rule is: Use comments to describe the functions in the header file. Also comment variables and static functions when it isn't obvious what they do.

No. Add comments to explain some required hacks or deviations. Otherwise the code shall be readable and comprehensive.

@TheCommoner282 @TheCommoner282 Should i name my function: copyMemoryFromLocationToDifferentNonoverlapingFunctionSizeInBytes() ? And that is a really simple function, i don't know how you would name printf().

A comment that you explains what lines below it do is just giving up on writing self documenting code

I was a mid-level dev when I started obsessively documenting the 'why'. Started out because I'm really forgetful and never could remember why I hard-coded this, check for that condition, etc.

Later it was helpful to CYA when crap-hit-the-fan situations and I could go back and read why.

Now I strongly discourage auto-documenting tools like GhostDoc unless you fill in the blanks with why the code is there. Devs can figure out the 'what', its the 'why' that can turn men/women into monsters.

@happygimp0

copyNonOverlaping(int* from, int* to, long size)

@netikras And what unit has size? Why do you use int pointers and not void pointers? Why do use long for size and not size_t? Comments are essential.

@TheCommoner282 The point is you can almost never use a function name that is short enough and says enough that it does not need comments.

@happygimp0 AFAIK when it comes to memory size is always counted in bytes.

And the units -- because I'm a java dev and it's all the same to me, just named/written differently.

@netikras When you use int pointers i would expect the size to mean the number of ints to copy.

This is why you need comments.

Comment why, not what.

A senior knows (or should know) where, where and in what quality to put comments in code and what amount of technical documentation should be appropriate.
Lots of unnecessary comments is just as bad as no comments at all.
Also good code redability and structuring can save you from writing most comments.

@TheCommoner282 I didn't say there are no redundant comments, there are a lot redundant comments. But comments are necessary to describe more details and corner cases.

I don't know what language your example uses. But a comment would be necessary for things: What happens when the user already exist? Which errors can be returned?

@happygimp0 No, this is why you need to understand the guidelines of domain development. And these most definitely must be specified outside of the code -- in project/domain/language docs.

@PaperTrail hmmm thats quite an interesting point... those "why" comments are the important ones. I think a lot of the other discussion in here anyway didnt think about "why" comments as compared to "what" comments

@PaperTrail I agree.

- the WHY comments*

- the public API methods/constants

- TODO/FIXME

^^ these are the only comments I expect to see in code.

* classified as "explain the hack", when "hacky" solutions are already discouraged in code. Could be reduced by covering affected parts of the code with unittests, using descriptive method names, that'd explain the WHYs. A unittest is a single ctrl+mousedown away, so any argument "it's hard to find and understand" is moot.

Comments decay over time, and are not as reliable as the code itself.

We write software. Soft. Malleable. So code changes. It's just what it does. Comments, however are that grey stuff faded into the background that you ignore most of the time while refactoring code.

@hardCoding A code review should catch that. If you change the code and the comments are no longer accurate, they need to be changed along with the code modification.. or removed altogether if they aren’t adding any value.

Comments to generate swaggerdocs. Readable code for the rest

@PonySlaystation I was in one project where some modules had comments for EVERY line. Even for something mundane like adding two integers.

@iiii wtf!

@PonySlaystation exactly what I've thought when I saw that.

Wrong way around. It's almost always keen juniors who comment everything excessively, not seniors (for good reasons already explained above.)

Shit comments: what the code is doing
Ok comments: why the code is doing it
Great comments: why it is NOT done a different way

if the functions and code in them are self explanatory I don't see why use comments. my professors would take points from projects with too little or too many comments, and i think that's valid. you gotta be able to tell easily what the code does, it's that simple. too many comments can pollute and detract from what needs highlighting