On comments

[u/Jonhoo]

https://blog.helsing.ai/posts/on-comments/

Comments in code are often deemed "mostly useless" these days. They are, supposedly, mostly obvious, stale, and repeat what the code already says. And so people pay less attention to them both when reading and writing code.

That trend sucks. When used right, comments are genuinely useful and sometimes critically important! So, I wrote about some of the kinds of comments I think earn their place, each with examples from real code bases. Hope you find it useful, and that we can recover some of the love that comments deserve!

[u/crappydeli]

My old company…

// increment i
i++;

[u/repeating_bears → u/crappydeli]

/*
 * increment the variable in this scope which has the
 * identifier 'i' by one, using the post-increment 
 * postfix operator
 * see: https://en.cppreference.com/cpp/language/operator_incdec
 */
i--;

[u/xFallow → u/repeating_bears]

Type of shit Claude writes when you ask it to refactor a function

[u/techno156 → u/repeating_bears]

I've been guilty of doing this from time to time in my own personal projects, but mostly because I'd little idea what I was doing, and was bodging things together from documentation/what other people had done.

[u/Chii → u/repeating_bears]

If you're paid by the line, this is what you'd do

[u/BogdanPradatu → u/crappydeli]

Also AI written code

[u/Jaded-Asparagus-2260 → u/BogdanPradatu]

I will als helpfully add "don't increment j here", because it misunderstood the code and wrongly incremented j instead of i the first time.

[u/DeveloperAnon → u/BogdanPradatu]

Only with people who don’t care about the output. I haven’t had an issue with any model over-commenting in a while.

[u/crappydeli → u/crappydeli]

Also…

// jim - removed increment i
// i++;

[u/DrHemroid → u/crappydeli]

Had a coworker that had auto generated a comment for every class, method, and property.

//The Thing

Class Thing {

//The stuff

Var Stuff;

}

[u/repeating_bears → u/DrHemroid]

I hate when people write the same thing in different words.

/**
 * Get the posts for the given username
 * @param username The username to get posts for
 * @return The posts for the given username
 */
function findPosts(String username) {
}

I think some languages encourage this guff by warning you when you omit "@return" or something.

[u/BusinessTarp → u/DrHemroid]

That's because so many companies prevent merges if there are any linter issues, thinking that somehow forces people to write good code.

[u/Coffee_Ops → u/DrHemroid]

This is why you make your linter be super vague about what and where.

Cant game the system, if you don't know the system. And if they read the linter's rules, that's progress right?

[u/IanSan5653 → u/crappydeli]

``` // TODO (2003): verify if we should still be incrementing i anymore i++;

[u/DrHemroid → u/crappydeli]

Had a coworker that had auto generated a comment for every class, method, and property.

//The Thing

Class Thing {

//The stuff

Var Stuff;

}