this post was submitted on 26 Nov 2023
707 points (89.2% liked)

Programmer Humor

19817 readers
624 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
 
you are viewing a single comment's thread
view the rest of the comments
[–] EnderMB@lemmy.world 27 points 1 year ago (1 children)

Comments don't describe the code. They describe the decision to use this business logic.

If you stick to good engineering practices, like small methods/functions, decoupling, and having testable code, you don't often need many comments to show what your code does. I always recommend a method signature, though, because you can save a few seconds by just saying that a block of code does, rather than me needing to read exactly how you turned one dict into another dict...

[–] MrSqueezles@lemm.ee 6 points 1 year 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.

[–] EnderMB@lemmy.world 3 points 1 year 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.