710
Bill is a pro grammer (sh.itjust.works)
you are viewing a single comment's thread
view the rest of the comments
[-] floofloof@lemmy.ca 35 points 1 year ago* (last edited 1 year ago)

If you're working with others, even simple code benefits from comments explaining what it's intended to do. Sure you can read code and get a good idea of what it seems to do, but you can't be sure that's what it was meant to do, or why it was meant to do that. Having a quick statement from the author enables you to work faster. And if you find a mismatch between the comment and the code, it's a smell that could mean a bug.

And for methods and functions it's particularly helpful to have a description at the top. Many IDEs will pop this up when you're using the method, so you can quickly confirm that it's appropriate for your needs and get your arguments in the right order.

I even comment code for myself because it will save me time when I return to the project months later.

No comments would be fine if you could trust that everyone writes code that does what it's intended to do and you can read code as quickly as you can read English. Maybe I'm a poor coder but I find neither of these is usually true.

[-] philm@programming.dev 10 points 1 year ago

Don't get me wrong comments != documentation (e.g. doc-comments above function/method).

I probably was a bit unprecise, as others here summed up well, it's the why that should be commented.

this post was submitted on 26 Nov 2023
710 points (89.3% liked)

Programmer Humor

19821 readers
535 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