1174
Comenting code
(lemmy.ml)
Post funny things about programming here! (Or just rant about your favourite programming language.)
Asking as a newbie programmer: how do you suggest we write comments that explain the 'why' part of the code? I understand writing comments explaining the 'what' part makes them redundant, but I feel like writing it the former way isn't adding much help either. I mean, if I created code for a clock, is writing "It helps tell what time it is" better than writing "It is a clock" ?
It would really help if someone could give a code snippet that clearly demonstrates how commenting the 'correct' way is clearly better than the way we are used to.
I recognize three kinds of comments that have different purposes.
The first kind are doc block comments. These are the ones that appear above functions, classes, class properties, methods. They usually have a distinct syntax with tags, like:
The primary thing this is used for is automatic documentation generators. You run a program that scans your codebase, looks for these special comments, and automatically builds a set of documentation that you could, say, publish directly to a website. IDEs can also use them for tooltip popups. Generally, you want to write these like the reader won't have the actual code to read. Because they might not!
The second kind is standalone comments. They take up one or more lines all to themselves. I look at these like warning signs. When there's something about the upcoming chunk of code that doesn't tell the whole story obviously by itself. Perhaps something like:
Sometimes it's tempting to use a standalone comment to explain what dense, hard-to-read code is doing. But ideally, you'd want to shunt it off to a function named what it does instead, with a descriptive doc comment if you can't cram it all into a short name. Alternatively, rewrite the code to be less confusing. If you literally need the chunk of code to be in its confusing form, because a less confusing way doesn't exist or doesn't work, then this kind of comment explaining why is warranted.
The last kind are inline comments. More or less the same use case as above, the only difference being they appear on the same line as code, usually at the very end of the line:
In my opinion, these comments have the least reason to exist. Needing one tends to be a signal of a code smell, where the real answer is just rewriting the code to be clearer. They're also a bit harder to spot, being shoved at the ends of lines. Especially true if you don't enforce maximum line length rules in your codebase. But that's mostly personal preference.
There's technically a fourth kind of comment: commented-out code. Where you select a chunk of code and convert it to a comment to "soft-delete" it, just in case you may want it later. I highly recommend against this. This is what version control software like Git is for. If you need it again, just roll back to it. Don't leave it to rot in your codebase taking up space in your editor and being an eyesore.
"tells the user the current time" would be an excellent comment for a clock
I'm not the best at commenting my code, but generally I just try to think of what information I'd want to know if looking at this 10 years from now
Imo comments are best used sparingly, don't bother commenting something that anyone with a basic understanding of programming would understand straight away by reading the code
Functions should generally be commented with what parameters are and what they're for, plus what they output
Here's an example where if I were to stumble onto this file 10 years from now, I might think wtf is this looking at it out of context, the comment explains why it exists and what it's used for
(we'll ignore the fact I totally didn't just add this comment because I suck at commenting personal projects)
Write comments that explain why the code isn't obvious just by reading it. Why did you do things the long way? What did you need to work around? Why didn't you do the thing that anyone reading the code would expect you to do?
Also write comments that explain the purpose of the functions you use, in case the names of those functions don't make it clear on their own.
the "what" is interesting on interfaces or when you generate documentation with some tool like sphinx or javadoc.
the "why" is interesting when you are somewhere inside a class or function and do something in a "strange" way, to work around a quirk in the codebase or something like that, or when you employ optimizations that make the code harder to read or atleast less obvious why somethings are done.
“Why” comments make more sense as application complexity grows.
You also have to consider interaction of the code with other external systems - sometimes external APIs force you to write code in ways you might not otherwise and it’s good to leave a trail for others on your team (and your future self…) about what was going on there.
100%. I also like to leave comments on bug fixes. Generally the more difficult the fix was to find, the longer the comment. On a couple gnarly ones we have multiple paragraphs of explanation for a single line of code.
I believe you confused the 'how' of commenting the 'why' with 'why' of commenting the 'why', if that makes sense.
I am already aware of and totally agree with the need to document your code in this fashion for the convenience of others and self. What I am troubled about is its implementation in real life. How does one write comment that explains the 'why' of the code? How would I know if I haven't accidentally written something that explains the 'what' instead or anything that is simply redundant? It seems like this portion is left out 'as an exercise for the reader'.
I think that, in many cases, “what” and “why” are very similar to each other or are closely related.
I’ve had an experience like this on more than one occasion - I come into an established code base for the first time. I’m working on a new feature/refactor/bug fix. I am reading through a function that is relevant to me, scratching my head a bit, and thinking “I think I see what this function is doing, but why did they do it such a screwy way?” Often there are no comments to give me any clues.
In the past, I have foolishly changed the code, thinking that I knew better… But what often happens is that I soon discover why my predecessor did something that looked so weird to me. They weren’t stupid - there was a reason for it! And then I end up putting it back…
Point being, in a situation like that the “what” and the “why” are going to have a lot of overlap. So, personally, I try to write comments that highlight assumptions that won’t be obvious from reading the code, external constraints that matter but don’t actually show up in the code, and so on.
I am far from perfect at it and I probably don’t write enough comments. But when I do, I try to write comments that will be reminders to myself, or fill in gaps in context for some hypothetical new person. I try to avoid comments that literally explain the code unless it’s particularly (and unavoidably) complex.
Not everything needs a comment - knowing when comments add value is the key... "what" vs "why" is usually a good indicator but some code just doesn't need a comment.
Doesn't need any comment:
int getCount() { return count; }
Absolutely needs a very extensive comment:
double getBojangleFlux { return fubar * .42; }
IMO, the most important parts are to document the actual intent of the code. The contract of what is being documented. Sure, it's only so useful in perfectly written code, but NO code is perfect, and few will come through later with full context already learned.
It makes it sooo mich easier to know what is intended behavior and what is an unchecked edge case or an unexpected problem. If it's a complicated thing with a lot of fallout, good documentation can save hours of manually lining up consequences and checking through them for sanity.
You might say, "but that's indication of bad code!". No. Not really. Consequences easily extend past immediate code doing things as trivial as saving data to the database without filtering, or having a publicly available service. Even perfectly coded things come up with vulnerabilities all the time due to underlying security issues. It's always great to have an immediate confirmation of what's supposed to happen whether it's immediate code or some library with a new quirk in a new version.
What I usually do is I explain what the function does and, if not self explanatory, explain why it does such thing. Like, with the clock example, I'd explain that it tells the time and then, if not immediately obvious, explain why the time needs to be known... Smth like that.
There is no "correct" way of commenting code. I personally think the more verbose, the better, but that's an unpopular opinion afaik. As long as the code can be understood, the comment is doing it's job.
PS, I'm also kinda new to programming, mostly doing JS and React stuff
spoiler
I love putting memes in comments :PMy comment game has gotten far better since I started doing live code reviews. Essentially I ask myself, “Would I feel the need to explain this to someone during a code review?” and if the answer is yes I add a comment.
Making up an example on the spot is kinda difficult for me, but I'd look at it this way with a bold statement, you should hope that most code won't need comments. Let's exclude documentation blocks that are super ok to be redundant as they should give a nice, consistent, human readable definition of what x thing does (function, constant, enum, etc.) and maybe even how to use it if it's non-intuitive or there are some quirks with it.
After that, you delve in the actual meat of the code, there are ways to make it more self explanatory like extracting blocks of stuff into functions, even when you don't think it'll be used again, to be used with care though, as not to make a million useless functions, better is to structure your code so that an API is put into place, enabling you to write code that naturally comes out high level enough to be understood just by reading, this thing is very difficult for me to pinpoint though, because we think of high level code as abstractions, something that turns the code you write from describing the what rather than the how, but really, it's a matter of scope, a print statement is high level if the task is to print, but if the task is to render a terminal interface then the print becomes low level, opposite is also true, if you go down and your task is to put a character onto stdout, then the assembly code you'd write might be high level. What I mean to say is that, once you have defined the scope, then you can decide what level of knowledge to expect of the reader when looking at your code, from there, if some process feels fairly convoluted, but it doesn't make sense to build an abstraction over it, then it is a good place to put a comment explaining why you did that, and, if it's not really clear, even what that whole block does
Interesting to see your opinion on how commenting shouldn't be mandatory. I specifically go the extra mile to ensure my code is readable for everyone, by naming my variables and functions to be as self-explanatory as possible and breaking down long expressions to store chunks in variables. This is why I was feeling confused as to what more I could add to explain my code better, though I must admit there are still considerable complex portions in some of my projects that would appreciate similar simplification.
Yes, I feel like some kind of bell should ring in your brain when something needs to be commented, most often if you struggled to write out the solution or you had to do a lot of digging from various places to achieve the final resulting piece of code, it doesn't make a lot of sense to pressure yourself into thinking you should comment everything, because some knowledge has to be assumed, nowadays you could even add that if someone completely extraneous to the codebase entered without any knowledge, they could feed the parts of code they need to understand into some LLM to get a feel for what they're looking at, with further feedback from actual devs though, you never know what random bs they might write.
Good one on the variables to store results of expressions, I agree with that method, though I always forget to do that because I get so lost in the pride of writing that convoluted one-liner that I think, "oh yeah, this is perfectly beautiful and understandable 😇", I have to check myself more on that.
So I'm not alone on that haha.
Sorry, what's the subject of that?
This is unfortunate for new programmers cause I think it's some kind of learned instinct rather than a hard rule
That's true, I don't know how it could be described as a hard rule though
I was just referring to my original question i.e. how I should write comments in my code to explain its working if I have already done so in the code itself
oh, I get it now
Unless you're writing something in the open source world, rarely does any code need comments at all.
That’s a hot take. If you want your code to be maintainable at all, it needs comments. If you’re part of a team, write comments for them. If someone else may take over your project after you move on, leave comments for them. And have you ever tried to read uncommented code you wrote a year ago? Leave comments for yourself.