1559
you are viewing a single comment's thread
view the rest of the comments
[-] Vigge93@lemmy.world 29 points 10 months ago* (last edited 10 months ago)

Comment should describe "why?", not "how?", or "what?", and only when the "why?" is not intuitive.

The problem with comments arise when you update the code but not the comments. This leads to incorrect comments, which might do more harm than no comments at all.

E.g. Good comment: "This workaround is due to a bug in xyz"

Bad comment: "Set variable x to value y"

Note: this only concerns code comments, docstrings are still a good idea, as long as they are maintained

[-] balp@lemmy.world 2 points 10 months ago

Docstring are user documentation, not comments. User documentation, with examples (tests), is always useful.

[-] Vigge93@lemmy.world 2 points 10 months ago

As long as it's maintained. Wrong documentation can often be worse than no documentation.

this post was submitted on 06 Jul 2024
1559 points (99.4% liked)

Programmer Humor

23133 readers
1385 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 2 years ago
MODERATORS