I disagree. When comments are essentially just a rephrasing of the class/method name or arguments it is not helpful and anything that is not helpful is cluttering up the code and making it harder to quickly see what the code is doing. I'd rather have no comments than comments like that.
I reserve comments for explaining why a section of code is needed or explaining how a complex algorithm works.
i = 0; // Set i to 0 is pointless.
if (last_output_vertex[i] == bounds[i]->length - 1) contibuting_bounds[i] = NULL; // stop outputting a bound if the entire bound has been output is helpful.
Then someone refactors the stop sign into a speed limit sign, leaves the comment unchanged, and years later someone else gets the fun job of figuring out which comments are lies
Also someone applied an auto code formatter to the entire codebase in the meantime, and the original file got moved a couple times, maybe just the path or into an entirely new repo. So the version control history is utterly obliterated as well…
[A photograph of a road signpost in front of a metal fence with a low, long building in the distance. The post has two signs on it. At the top is an octagonal sign, filled red with a white outline, reading "STOP". Beneath it is a rectangular sign with an arrow pointing up to the stop sign, and text reading "THIS IS A STOP SIGN".]
I am a human who transcribes posts to improve accessibility on Lemmy. Transcriptions help people who use screen readers or other assistive technology to use the site. For more information, see here.
Thanks! Not sure if there's been other people doing any or not, but for my part I just do them when I find the time, which unfortunately isn't all that often.
Sounds like a good use of comments. Explain why, not how. (that should be readable from the code for the most part. Unless you're having function calls like xmmmuldp (simd) )
This actually makes a lot of sense. A computer executing the code and a human maintaining it need to know different things. A human needs to knon what the code does on a high level (what the programmer intended), how it handles (or does not handle) edge cases, etc. A computer only needs to know how to run the code at a super low level. Without comments, it is impossible to know if code is doing the right thing, or what is expected from the caller.
Better: I've encountered a pair of booleans that appear to be exact opposites but aren't. To protect the guilty I've changed the words: isOpen and isClosed, when one is true the other is false and vice versa, EXCEPT that while something can't be both open and closed at the same time, it is possible for something to be not open and not closed.
I would hope it modifies the original. It's implied in the name. A function that returns all but the first item should be named something like tail or without_first_item.
Let's face it, such comments usually cause more problems than do good. If someone changes the code and forgets to modify the comment, the reader might favor one or another at random. "Stop sign" example isn't the best but you get my point.
Comments at best should explain some non-obvious logic, or some sort of reasons for implementing one way or another. For SDKs and packages overall, public APIs should also be commented. The rest imo should be readable from code.
A form of "self documentation" I like to do is create variables for conditions before using it in an if statement. If you break down a funky conditional into easy to read variables it becomes a lot more clear what it's trying to do.
If someone changes the code and forgets to modify the comment, the reader might favor one or another at random.
Hence why you should comment why, not how/what.
// slow down traffic before crossing busy main road
Now you can change the stop sign to a yield without touching the comment. Or judge that the comment can be removed if it's clear the main road does no longer exist.
Except realistically the standards around commenting are going to change dramatically over the next decade because of generative AI.
I've been toying with selecting 'comments' as my language of choice for my next hobby project to see if pseudocode and comments can lead to a language agnostic project that can reliably be reproduced in multiple languages.
As the tech gets better, more and more of the job is going to be writing comments about what the code should do as opposed to documenting what it does do.
Just write your code, so that you (almost) don't need comments (i.e. simple to read). The problems with (most) comments won't be solved by AI.
(in-code) comments only make sense for me in roughly these scenarios:
complex piece of math possibly from a paper (e.g. a ref to the paper where it is explained)
function doc, here AI may really help at some time (right now, I'll rather write it myself, AI represents this post very well in an even more verbose and literate way than the typical junior dev...)
This couples intentions to the code which in my example would be dynamic.
That's going to be a bad time.
My point is that the conventions that used to be good for the past 50 years of development are likely going to change as tooling does.
Programming is effectively about managing complexity.
Yes, the abstraction of a development language being the layer at which you encode intention rather than in comments is better when humans are reading and writing the code itself.
But how many projects have historically run into problems when a decade earlier they chose a language that years later is stagnating in tooling or integrations versus another pick?
Imagine if the development work had been done exclusively in pseudocode and comments guiding generative AI writing in language A. How much easier might porting everything to language B end up being?
Language agnostic development may be quite viable within a year or so.
And just as you could write software in binary, letting a compiler do that and working with an abstracted layer is more valuable in time and cost.
I'm saying that the language is becoming something which software can effectively abstract, so moving the focus yet another layer up will likely be more valuable than clinging to increasingly obsolete paradigms.