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.
Comment from my group project teammate. You don't need to comment every line lol
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.
It's an art, not a science. Which is where I think a lot of people misunderstand software development.
I mean, it's better to have to many comments than not enough
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.
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.
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).
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.
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.
Legit, I'll take this over the undocumented spaghetti I too often see written by "professionals".
This is so wrong. I would absolutely prefer no comments over incorrect comments, which is exactly what happens when things get over commented
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.
} // End of if
This brings back trauma
okay but which 'if' is ending ??
The outer most. (There were 4 layers of nested ifs.)
too few. i like to have a nice big gap on the left of the code so theres a place to write notes when i screenshot the code
There is usually no such thing as too many comments. There is a point to keep them to the point though
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.
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.
While this is true, an alternative is to name your variables and functions descriptively so that when you see number_of_cats you know that variable is the number of cats, and buyAnotherCat() is a function that increases the number of cats.
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.
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
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!
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.
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.
me in a group project ending up doing all the work