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

Programmer Humor

19503 readers
1130 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 1 year ago
MODERATORS
 
you are viewing a single comment's thread
view the rest of the comments
[โ€“] [email protected] 35 points 11 months ago* (last edited 11 months ago) (1 children)

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.

[โ€“] [email protected] 10 points 11 months 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.