Programmer Humor

18962 readers

454 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

Keep content in english
No advertisements
Posts must be related to programming or programmer topics

founded 1 year ago

MODERATORS

[email protected]

707

Bill is a pro grammer (sh.itjust.works)

submitted 9 months ago by [email protected] to c/[email protected]

99 comments fedilink hide all child comments

you are viewing a single comment's thread
view the rest of the comments

[–] [email protected] 6 points 9 months ago (1 children)

I agree for inline code comments, like, "# Save the sprocket", right above the line that saves the sprocket. Does this include documentation? Because when I see a prepareForSave function that references 10 other functions and I just want to know, "Is this mutating and how is it preparing for save and when should I call it?", having the author spend 15 seconds telling me is less time consuming than me spending 5 minutes reading code to find out. Anyone who has read API docs has benefited from documentation.

[–] [email protected] 3 points 9 months ago

No, commenting a function should be commonplace, if not only so that your IDE/editor can use the documentation when the signature is found elsewhere in your code.

Within a function, though, basically means that something gnarly is happening that wouldn't be obvious, or that the function is doing more than it (probably) should.