this post was submitted on 28 Sep 2024
1181 points (99.0% liked)

Programmer Humor

32596 readers
647 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 2 months ago* (last edited 2 months 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.

[โ€“] jbrains 11 points 2 months ago

Write comments that explain why the code isn't obvious just by reading it. Why did you do things the long way? What did you need to work around? Why didn't you do the thing that anyone reading the code would expect you to do?

Also write comments that explain the purpose of the functions you use, in case the names of those functions don't make it clear on their own.

load more comments (24 replies)