this post was submitted on 28 Sep 2024
1208 points (99.1% liked)

Programmer Humor

32472 readers
600 users here now

Post funny things about programming here! (Or just rant about your favourite programming language.)

Rules:

founded 5 years ago
MODERATORS
 
you are viewing a single comment's thread
view the rest of the comments
[–] [email protected] 24 points 1 month ago* (last edited 1 month ago) (25 children)

Asking as a newbie programmer: how do you suggest we write comments that explain the 'why' part of the code? I understand writing comments explaining the 'what' part makes them redundant, but I feel like writing it the former way isn't adding much help either. I mean, if I created code for a clock, is writing "It helps tell what time it is" better than writing "It is a clock" ?

It would really help if someone could give a code snippet that clearly demonstrates how commenting the 'correct' way is clearly better than the way we are used to.

[–] [email protected] 8 points 1 month ago (3 children)

“Why” comments make more sense as application complexity grows.

You also have to consider interaction of the code with other external systems - sometimes external APIs force you to write code in ways you might not otherwise and it’s good to leave a trail for others on your team (and your future self…) about what was going on there.

[–] [email protected] 5 points 1 month ago

100%. I also like to leave comments on bug fixes. Generally the more difficult the fix was to find, the longer the comment. On a couple gnarly ones we have multiple paragraphs of explanation for a single line of code.

load more comments (2 replies)
load more comments (23 replies)