279
submitted 1 week ago* (last edited 1 week ago) by [email protected] to c/programmer_humor

Comment from my group project teammate. You don't need to comment every line lol

top 50 comments
sorted by: hot top controversial new old
[-] [email protected] 70 points 1 week ago* (last edited 1 week ago)

Writing good comments is an art form, and beginner programmers often struggle with it. They know comments mostly from their text books, where the comments explain what is happening to someone who doesn't yet know programming, and nobody has told them yet that that is not at all a useful commenting style outside of education. So that's how they use them. It usually ends up making the code harder to read, not easier.

Later on, programmers will need to learn a few rules about comments, like:

  • Assume that whoever reads your code knows the programming language, the platform and the problem domain at least in general terms. You are not writing a teaching aid, you are writing presumably useful software.
  • Don't comment the obvious. (Aside from documentation comments for function/method/class signatures)
  • Don't comment what a line is doing. Instead, write your code, especially names for variables, constants, classes, functions, methods and so on, so that they produce talking code that needs no comments. Reserve the "what" style comments for where that just isn't possible.
  • Do comment the why. Tell the reader about your intentions and about big-picture issues. If an if-statement is hard to parse, write a corresponding if clause in plain English on top of it.
  • In some cases, comment the "why not", to keep maintenance programmers from falling in the same trap you already found.
[-] [email protected] 54 points 1 week ago

Commenting the why not is key. Half my comments are explaining why I had to use this hack as a warning that the obvious fix doesn't work!

[-] Tamkish 20 points 1 week ago* (last edited 1 week ago)

I would argue that if an if statement is hard to parse, replace the entire condition with simpler to read (but way more specific) variables that you assign values (the original condition expression) in the line above. No need for comments in that case

[-] [email protected] 13 points 1 week ago* (last edited 1 week ago)

Good advice, just to add to this:

  • Comments should be part of code review, having at least two pairs of eyes on comments is crucial. Something that's obvious to one person maybe isn't so obvious to another. Writing good comments is as hard or harder than writing good code, so having it checked for mistakes and quality is a must
  • Comments aren't the actual documentation and aren't a reason not to write documentation to go along with your code. Often I see larger projects where each class and function is documented in comments, but the big picture and the how and why of the overall structure is completely missing. Remember that in the real world you often have a lot of folk that need to understand how the code works, who aren't programmers themselves. They can't read the code or don't have access to the code. Writing documentation is still important.
  • Please for the love of god when you change code, check if the comments need to be updated as well. Not just around the immediate area, but also the entire file/class and related files. I've worked on large codebases before with a high wtf factor and having the code do something different to or even opposite the comments is a nightmare. I'd rather have no comments than wrong comments.
[-] [email protected] 8 points 1 week ago

This is a notoriously bad book. If you read the part about comments (which I don't know about, and am willing to accept is good) make sure to skip everything else because Robert Martin is a fraud.

[-] [email protected] 2 points 1 week ago

Agreed, removed

[-] [email protected] 7 points 1 week ago

I'd rather have no comments than wrong comments.

I’ve seen cases of outdated comments in the same line of code it’s describing. People suck at maintaining comments.

[-] [email protected] 11 points 1 week ago

Don’t comment what a line is doing. Instead, write your code, especially names for variables, constants, classes, functions, methods and so on, so that they produce talking code that needs no comments.

Over and over and over again in my experience this just doesn't work. Readable code does not substitute for comments about what the code should be doing.

load more comments (4 replies)
[-] [email protected] 64 points 1 week ago

Software devs in general seem to have a hard time with balance. No comments or too many comments. Not enough abstraction or too much, overly rigid or loose coding standards, overoptimizing or underoptimizing. To be fair it is difficult to get there.

[-] MagicShel 42 points 1 week ago

It's an art, not a science. Which is where I think a lot of people misunderstand software development.

[-] JackbyDev 21 points 1 week ago
[-] [email protected] 2 points 1 week ago

okay but which 'if' is ending ??

[-] JackbyDev 2 points 1 week ago

The outer most. (There were 4 layers of nested ifs.)

load more comments (1 replies)
[-] brettvitaz 2 points 1 week ago

This brings back trauma

load more comments (1 replies)
[-] [email protected] 17 points 1 week ago

I mean, it's better to have to many comments than not enough

[-] [email protected] 51 points 1 week ago

It's better to have useful comments. Long odds are that somebody who writes comments like this absolutely isn't writing useful comments as well - in fact, I'm pretty sure I've never seen it happen. Comments like this increase cognitive overhead when reading code. Sure, I'd be happy to accept ten BS useless comments in exchange for also getting one good one, but that's not the tradeoff in reality - it's always six hundred garbage lines of comment in exchange for nothing at all. This kind of commenting usually isn't the dev's fault, though - somebody has told a junior dev that they need to comment thoroughly, without any real guidelines, and they're just trying not to get fired or whatever.

[-] [email protected] 4 points 1 week ago

Wonderfully said, I’ll be linking your response

[-] [email protected] 29 points 1 week ago* (last edited 1 week ago)

Universities often teach students to write a lot of comments, because you are required to learn and demonstrate your ability to translate between code and natural language. But this is one of the things that are different in professional environments.

Every comment is a line to maintain in addition to the code it describes. And comments like this provide very little (if any) extra information that is not already available from reading the code. It is not uncommon for someone to alter the code that the comment is supposed to describe without changing the comment, resulting in comments that lie about what the code does, forcing you to read the code anyway.

It's like if you were bilingual, you don't write every sentence in both languages, because that is twice as much text to maintain (and read).

The exception of course, being if you are actually adding information that is not available in the code itself, such as why you did something a particular way.

[-] [email protected] 15 points 1 week ago

Yup this is the real world take IME. Code should be self documenting, really the only exception ever is "why" because code explains how, as you said.

Now there are sometimes less-than-ideal environments. Like at my last job we were doing Scala development, and that language is expressive enough to allow you to truly have self-documenting code. Python cannot match this, and so you need comments at times (in earlier versions of Python type annotations were specially formatted literal comments, now they're glorified comments because they look like real annotations but actually do nothing).

[-] [email protected] 3 points 1 week ago

Exactly! Write your code to be as clear and self-descriptive as possible, and then add a comment if something is still not immediately obvious.

[-] [email protected] 5 points 1 week ago

If I see comments explaining every other line, especially describing “what” instead of “why”, I assume the code was written by a recent grad and is going to be bad. Describing what you are doing looks like you are doing a homework assignment.

Like on that line, obviously we’re initializing a variable, but why 1 instead of 0? Could be relevant to a loop somewhere else, but I guess I’ll have to figure that out by reading the code anyways.

[-] [email protected] 3 points 1 week ago

It's like if you were bilingual, you don't write every sentence in both languages, because that is twice as much text to maintain (and read).

This is a very good analogy. And just like with natural languages, you might have an easier time expressing an idea in one language but not the other. Comments should provide information that you find difficult to express with code.

[-] cheddar 5 points 1 week ago* (last edited 1 week ago)

If there are too many comments, it means you have to support them just like the code itself. Otherwise, like any other documentation, comments will quickly go out of sync.

load more comments (2 replies)
[-] [email protected] 16 points 1 week ago

More useful would be what sort of values is acceptable there. Can I use team number 2318008? Can I use team 0? If not, why not? WHY / WHY NOT is often useful.

[-] [email protected] 15 points 1 week ago

I am not a programmer, I just barely wrote one bash script in the past. But I'd say more comments are better than too few.

When I later wanted to edit it, I got completely lost. I wrote it with absolutely no comments.

[-] [email protected] 21 points 1 week ago

Bash is a shit „language” and everytime i need to write the simplest thing in it I forget which variable expansion I should use and how many spaces are the right amount of spaces. It’s impossible to write nice to read bash, but even in C you can write code that comments itself.

[-] [email protected] 9 points 1 week ago

It's perfectly possible to write nice to read bash, and to also make is safe to run and well-behaved on errors.

But all the three people that can do those (I'm not on the group) seem to be busy right now.

load more comments (2 replies)
[-] [email protected] 6 points 1 week ago

bash sucks but i don’t agree. Some simple rules like regularly use intermediate variables with useful names and never use shorthand arguments goes a long way.

[-] [email protected] 3 points 1 week ago

I've been programming for almost 25 years and I'd still rather see too many comments than too few. A dogmatic obsession with avoiding comments screams "noob" just as much as crummy "add 1 to x" comments. If something is complex or non-obvious I want a note explaining why it's there and what it's supposed to do. This can make all the difference when you're reviewing code that doesn't actually do what the comment says it should.

load more comments (4 replies)
[-] [email protected] 14 points 1 week ago

Reminds me of every fuckin PR I do for the Indian contractors that were sold to us as “senior devs” but write code like a junior and you better believe every other line has the most obvious fucking comment possible

[-] [email protected] 7 points 1 week ago

Better than writing beginner level crap that is at the same time super cryptic and not documenting at all. We have a bunch of that in our codebase and it makes me wonder why these devs are writing extension methods for functionality already built into the standard libraries.

[-] [email protected] 2 points 1 week ago

Better than writing beginner level crap that is at the same time super cryptic and not documenting at all. We have a bunch of that in our codebase and it makes me wonder why these devs are writing extension methods for functionality already built into the standard libraries.

[-] [email protected] 13 points 1 week ago

Let the code explain the „how“, use comments to explain the „why“.

[-] [email protected] 12 points 1 week ago

It's much worse to learn development while being lazy about commenting. Or adding them all just before sending your source code to the teacher.

[-] [email protected] 10 points 1 week ago* (last edited 1 week ago)

Lol that's exactly what this was. I wrote this python script, and he went through and added comments like this a day before the deadline.

Not trying to throw shade on him though, it's more the university's fault for not explaining what makes a useful comment. I just thought it was funny

[-] [email protected] 9 points 1 week ago

When people read my code, they usually say they like that I comment so much, it makes it easier to understand what's happening.

I say, I comment so much because my memory is terrible. It's for me!

[-] [email protected] 4 points 1 week ago

I've worked in a few startups, and it always annoys me when people say they don't have time to do it right. You don't have time not to do it right - code structure and clarity is needed even as a solo dev, as you say, for future you. Barfing out code on the basis of "it works, so ship it" you'll be tied up in your own spaghetti in a few months. Hence the traditional clean-sheet rewrite that comes along after 18-24 months that really brings progress to its knees.

Ironically I just left the startup world for a larger more established company and the code is some of the worst I've seen in a decade. e.g. core interface definitions without even have a sentence explaining the purpose of required functions. Think "you're required to provide a function called "performControl()", but to work out its responsibilities you're going to have to reverse-engineer the codebase". Worst of all this unprofessional crap is part of that ground-up 2nd attempt rewrite.

[-] [email protected] 4 points 1 week ago

Ironically I just left the startup world for a larger more established company and the code is some of the worst I’ve seen in a decade. e.g. core interface definitions without even have a sentence explaining the purpose of required functions. Think “you’re required to provide a function called “performControl()”, but to work out its responsibilities you’re going to have to reverse-engineer the codebase”. Worst of all this unprofessional crap is part of that ground-up 2nd attempt rewrite.

I think this is actually quite common in commercial code. At least, for most of the code I've seen. Which is why I laugh most of the time when people imply commercial code is better than most open source code. It's not, you just cannot see it.

load more comments (2 replies)
[-] [email protected] 9 points 1 week ago
load more comments (1 replies)
[-] [email protected] 4 points 1 week ago

There is usually no such thing as too many comments. There is a point to keep them to the point though

load more comments (4 replies)
[-] [email protected] 4 points 1 week ago* (last edited 1 week ago)

#tell me what it's about

print("tell me about it")

[-] [email protected] 4 points 1 week ago* (last edited 1 week ago)

#team number = 1 team_num = 1

Comments lie to you!

load more comments
view more: next ›
this post was submitted on 10 Jun 2024
279 points (94.9% liked)

Programmer Humor

18099 readers
2132 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