Developer accused of being indecisive refuses to commit.
99% of code comments have always indicated slop, even prior to AI
If it’s not immediately obvious what your code does by reading it, you should rewrite it so it is. Putting a comment in rather than refactoring is akin to trashing a hotel room and just leaving a note saying sorry.
It’s giving “I don’t need to annotate my code because my code is self-documenting” energy…
Cool, so you’d rather surf the web for documentation than read it in your editor/IDE. I understand
I’d rather the code itself is readable with well-named variables and methods.
There are situations where comments are helpful though
// this foos the bar foo(bar);Helps nobody
// this might seem weird, but we had to add this because some customers were complaining about unfood bars and the rest don't seem to mind either way foo(bar);Is much more helpful
I’d rather the code itself is readable with well-named variables and methods.
Unfortunately, sometimes a level of specificity is needed that can’t be expressed in a method name alone, unless you make that method name super long. The method name can’t always convey:
- Time and space complexity
- Side effects
- Thread safety
- Possible exceptions
- Preconditions and postconditions
- Edge cases
Sure, some of this can be communicated in the implementation, but that means that users need to control-click the function instead of just hovering to see the comment. And sometimes the implementation is a secret or at least in a different file from the declaration
deleted by creator
Upvoted because you sound exactly like my old school MCU professor. Old school C guy who would die on the hill that overly-commented code is smell. He spat on arduinos and told us we’d be better off doing any hobby projects on ATmega, lol. I assume your downvotes are from folks in the new school, but I’d hold that your old school values are still very much needed today.
Depends on how old school. Some of those older languages absolutely need explanation everywhere.
Absolutely. Its not always possible to write self explantory code. Especially when you have to use some narly uncommon Syntax a short comment can improve the readability Quite a lot. Personally I like to comment my Parameter Expansions in Bash, since I find its Syntax quite hard to remember and therefore it can be a little bit challenging to infer the functionality just by looking at a bunch of special characters.
You knew you were going to be downvoted, right?
Yes!
And comments are wrong… they tell things about a previous version of the code, since the code has been modified since the comment but the comment has remained untouched!
And wheneit is the original code, the true comment would be “copied from stackoverflow” (or nowadays from my favorit AI). In both cases, if it is not obvious while reading, the dev wasn’t knowing what he was doing while writing…
Comments shouldn’t explain what you’re doing, but why you’re doing it
That’s what the function name is for
If you can’t succinctly describe a function by its name, it’s too big and should be split up
If it still needs explaining, the only acceptable comment is an ADR reference to the doc with the actual detail
I disagree. Function names should describe, as clearly and as precisely as possible, what they do rather than why they do it in one particular way.
I find comments helpful when the implementation of a function is surprising, i.e. it diverges from patterns one might normally expect for similar tasks. Specialized performance optimizations would be one example I can think of.ADRs are useful, but I’m not sure they make much sense for implementation details at the level of a function.
All that said, I do agree that functions should be clear in name and content and I think comments should be rare.
A function name says what it does, not why. Or do you name your functions “thisLooksABitWeirdButItsBecauseThePrintFunctionDoesntSupportKanji”? 😋
A function which is only used once is code smell to me. A function with 200 lines of code and a few comments here and there which I can read from to to bottom can be much more readable than 20 10 line functions for which I have to jump back and forth.
A 200 line function tells me the code is very likely to be inadequately unit tested and/or is going to be fragile when it’s changed in the future.
Functions aren’t only for code reuse, they are for structuring your code.
I agree with 200 functions being bad, but breaking them up into private functions won’t help you with unit testing, unless you do the other sin of testing private functions. Sometimes you end up with large functions, but when you do it might be a good time to consider creating a new class to spread the responsibilities a bit.
In my experience function calls are mostly for breaking my flow of reading. I don’t see why you couldn’t add structure with newlines and comments.
It could be that I’ve only seen bad code and if you do it good it actually improves readability. But I think there’s more chance I’ll encounter a unicorn than good code.
brother back in the day you got 8 characters for a function name. that’s why c functions have awful names.
Lemme guess, you read that ‘clean code’ book and spout its BS non-stop.
I was kinda done responding to this thread, but it has to be made clear that Bob Martin is a wanker
And avoiding writing shit code doesn’t have to have anything to do with that bigoted twat
What about a comment like “The API returns stuff basically in random order, you gotta sort them first”?
Put that code in a method called something like sortRandomApiResults().
So now you need 30 different functions that sort things, named for each reason you need to sort things?
What’s the alternative? Write an inline sort routine 30 times?
I’m not so sure the example is particularly good. Assuming the sort is just a one line call to a library routine, then the comment would be unnecessary. You call the API, then you sort the results and it should be obvious to any maintenance programmer why. Don’t comment obvious stuff.
If you are doing this 30 times, then put the API call and the sort in a subroutine called callApiAndSort().
The suggestion was that a comment be used when the reason for the sort was not obvious. Not that every sort be commented to explain why. So there’s no reason why you’d wrap every sort call in a custom subroutine either.
The alternative is to just call the sort function and add a comment if the reason why it’s being sorted isn’t obvious rather than making a new function so that the function name can act as the comment.
I just see “never do x, no exceptions” as overly constraining yourself when sometimes a comment might be a better option than jumping through a hoop that involves having a function named “sortRandomAPIResults” just to avoid ever using a comment. Even goto statements have cases where you get better code from just using goto than everything required to avoid it.
Better to understand the purpose of the thing you are doing and to be aware of the pitfalls using it might subject you to. Yeah, there are a ton of comments out there that are useless or even misleading, but there are helpful ones, like if a function encodes some data for some specific spec, a comment that includes information about that spec can help. Like url for documentation, or a description of the relevant fields it’s filling in. Yeah, you could get that from data structures and looking at the code, but it’s a bit more mental effort to do that, plus it assumes the code is correctly doing what the programmer intended it to do.
If some code looks very close to some standard math thing but is slightly different, is that a bug, a way that this case differs from the usual case, or an optimization? Iirc Carmack introduced some optimisations for 3d rendering doom that even he wasn’t fully aware of how they worked, just that they were able to test the output over the range of relevant inputs and determined that it always gave a solution that was good enough to be able to skip some slower method that was easier to understand.
And there’s also language barriers. Some code that looks very descriptive to you might not be so obvious to someone who isn’t a native speaker or even just has sufficient cultural differences to not pick up on a reference. I’d bet that translation tools, that don’t always do great at translating meaning rather than words, will struggle even more if that meaning is encoded in C++ as well as English.
Sets are unordered, no need for this specific comment
What if the API returns a randomly ordered list?
That should be evident from the code and probably a unit test if it matters that the data is sorted in some way
No comment needed
I’d still prefer a note saying “Look out, I shat in that drawer” to no warning at all
Slightly better than the worst scenario is a lower bar than acceptable IMO
I assumed it was immediately obvious that shitting in a drawer isn’t acceptable
Look, if you’ve seen the shit I have, frankly it’s not a given
Code commenting has gone through different phases over the years. Back when many languages weren’t very readable, it was important to use comments. We’ve migrated mostly to self-documenting code, but I’ve never left them completely behind.
As an example, I do a fair bit of SCAD work. It’s a functional language that is often not obvious–many commands are repetitive. So I’ll often use headers at the least.
Even working in C, I’ll often document things about parameters and return values so that I don’t have to read through the code when I go to use the function. They have their place, but if you have more comments than code, that’s a bad smell.
How do you know the comments are correct, or that they have been maintained along with the code over the years?
If you don’t know or trust the author, you don’t know whether they’re correct. And if something doesn’t compile or there ends up being issues, you might have to read through the code more carefully to figure out what’s going on.
But if you don’t know or trust the author of self-documenting code, you can still run into the same issues. Comments are just another part of the code.
Comments are by definition not part of the code.
And no, I never trust the author - even if it was me 6 months ago.
Not to mention all the other programmers that might have fiddled with it. Not mention changes in the code since it was written, where the comments weren’t updated.
As a maintenance programmer with 35 years experience, the first thing I do is delete the comments. My experience says they get in the way and can’t be trusted. Read the code, understand the code, and figure why it’s doing what it’s doing. Don’t worry about what it might have been doing 10 revisions ago when the comments were last updated.
Fair, I’ll make an allowance for doxygen/javadoc style tagged comments in low level languages and for libraries where you don’t expect people to read the implementation
Sometimes I rather have a slop library with an actual documentation of what my function does than mystery function #920 that is actually critical to the thing. The mystery function is actually self documenting you see, but you need to search for examples in the code to actually know what it does.
I do both comments and self documenting code, as self documenting code doesn’t work without context
Are you saying that my comment “Removed straightness from the game” is not necessary?
So you are in favour of unoptimised code?
I love how everyone’s missing your point
By default, we write readable and maintainable code. But sometimes the results of profiling indicate that we need to optimize a function so much that it stops being readable. In these cases, you need comments so people can still understand how the function works, so they know how to use and change it if necessary
This is more common in high-performance and real-time applications (the sorts of applications where you need to be thinking about cache locality, CPU pipelining, etc.)
I don’t know if I am too clueless to grasp a higher dimensional point you are trying to make or you want to say that comments optimize code
To my understanding comments are ignored by compliers and runtimes having them makes no difference when the code is actually running. I may be wrong on this point though.
I was referring to this line
If it’s not immediately obvious what your code does by reading it, you should rewrite it so it is
Code that is written for human readability omits an amount of optimisations languages have in compilers, jits, and runtimes. As code is read by machines several orders of magnitude more then a human, why make the code 20 to 30% slower for a computer to read just so an engineer can read it 40% faster?
With that being said, not all code needs to be optimised that hard. There are times where you don’t need that 20 to 30% increase in application runtime and writing code that is readable or “self documenting” works well enough.
Oh thanks I see it now
Most code isn’t unreadable, because it’s optimized for performance, but rather because it is needlessly complicated and should be refactored. And then reducing this complexity is likely to improve performance as well.
For example, you might draft out an algorithm with a nested loop, and then you look at it once more and realize that it can be done with a single loop. That’s very likely easier to grasp and massively better for performance, too.
If you do need to make code unreadable for performance reasons, then absolutely do make use of comments. Although I would still recommend making it understandable without resorting to comments, if possible.
Function, variable and test names can help to explain a lot. Error and log messages can be used to write out really clearly what is happening. And they have the huge advantage compared to code comments, that they show up in at least two places, which makes them more likely to be read and updated.
As someone else already wrote, the why should still be explained with a code comment. It rarely makes sense to explain implementation details in log statements…
We’re kinda breaking from the shitposting theme here, but this is good discussion
Honestly unless you’re writing DSP or 3D engine code, micro-optimisations are an absolute waste of time. Either you’re working in a low enough level language that the compiler is going to do a better job than you anyway or you’re working in a high level language where such optimisations are pissing in the wind
And if you’re doing DSP shit in 2026, let me talk to you about the good news of zig
First of all, most of the cost of a system comes from maintenance after implementation. So the idea that “an engineer can read it 40% faster” isn’t as trivial as you make it sound.
Secondly, well laid out code that doesn’t need to be commented is generally simpler to write, easier to test and easier for the original developer to conceptualize when he’s writing it. I’ve seen lots of programmers get lost in the complexities of their own approach because they don’t organize their code properly.
Finally, my understanding is that modern compilers optimize lots of things automatically, probably better than an engineer would and on all of the code. Write your code for the human to read it, let the compiler do its thing, and optimize by hand only that tiny percentage of code that causes performance issues.
