this post was submitted on 10 Jun 2024
282 points (94.9% liked)

Programmer Humor

19480 readers
615 users here now

Welcome to Programmer Humor!

This is a place where you can post jokes, memes, humor, etc. related to programming!

For sharing awful code theres also Programming Horror.

Rules

founded 1 year ago
MODERATORS
282
submitted 5 months ago* (last edited 5 months ago) by [email protected] to c/[email protected]
 

Comment from my group project teammate. You don't need to comment every line lol

you are viewing a single comment's thread
view the rest of the comments
[–] [email protected] 13 points 5 months ago* (last edited 4 months ago) (2 children)

Good advice, just to add to this:

  • Comments should be part of code review, having at least two pairs of eyes on comments is crucial. Something that's obvious to one person maybe isn't so obvious to another. Writing good comments is as hard or harder than writing good code, so having it checked for mistakes and quality is a must
  • Comments aren't the actual documentation and aren't a reason not to write documentation to go along with your code. Often I see larger projects where each class and function is documented in comments, but the big picture and the how and why of the overall structure is completely missing. Remember that in the real world you often have a lot of folk that need to understand how the code works, who aren't programmers themselves. They can't read the code or don't have access to the code. Writing documentation is still important.
  • Please for the love of god when you change code, check if the comments need to be updated as well. Not just around the immediate area, but also the entire file/class and related files. I've worked on large codebases before with a high wtf factor and having the code do something different to or even opposite the comments is a nightmare. I'd rather have no comments than wrong comments.
[–] [email protected] 8 points 5 months ago (1 children)

This is a notoriously bad book. If you read the part about comments (which I don't know about, and am willing to accept is good) make sure to skip everything else because Robert Martin is a fraud.

[–] [email protected] 2 points 4 months ago

Agreed, removed

[–] [email protected] 7 points 4 months ago

I'd rather have no comments than wrong comments.

I’ve seen cases of outdated comments in the same line of code it’s describing. People suck at maintaining comments.