I comment everything that I think would be useful for me when revisiting the code a year later. Usually "why" and "why not". Sometimes a short "what" when the code is complex and it's nice to see the sequence more clearly.
What's not so useful: mandatory comments. A public API should be thoroughly documented, but some shops insist on writing comments for every function in the code, even private ones and even if its purpose is so obvious that the comment just rephrases its name. This practice is not only a waste of time, but also insensitizes you about comments and teach you to ignore them.
Other wasteful comments are added by some tools. I hate the one that marks every loop wiht a //for or //try comment.
For some reason a lot of syntax highlighting color schemes de-emphasize comments, making them low contrast, which is probably because a lot of mandatory / generated comments are low information. Get rid of mandatory and generated comments, and change your color scheme to make them a bright neon colour instead (on a dark theme) to draw the attention, because IF something is commented then it's important.
I disagree with this. Comments are important but not every time you're in that part of the code. You might already know from just the code what's going on, or have already checked out the comments. There's no value to them always being emphasized. That would be like reading all NPC dialogs every time in an RPG.
If there is a comment is should be important enough to read it every single time you are near that area of code even if looking for something else in the file! They should be a reminder of something important and not obvious in the code - otherwise I'll just read the code.
Note that I distinguish comments from API documentation even though they are often both in the same code and use the same comment syntax.
If there is something really important worth rereading over and over again, put «NOTE: » before it and let your editor highlight it for readers of your code
> I comment everything that I think would be useful for me when revisiting the code a year later.
Do you code solo or do you work with a team? If so, how large is the largest team you've worked with?
I used to be a dogmatic "all comments are code smells" person and, to a large degree I still am. But working on a very (and I mean VERY) large code-base that is actively developed and maintained by hundreds of other software developers, I have relaxed my position slightly into the "if you need to do something weird, explain why" ... because a large legacy system that lives in a business environment of tight deadlines means that there are often weird things that need to be done to keep things moving at a pace that the business is willing to pay for.
Anyway, one of the many reasons that I argue AGAINST code comments is that the comments become part of the code and therefore require maintenance. But few people read comments unless they are stuck trying to understand something. This "psychological invisibility" is even enforced by the fact that most code editors will grey out comments in order to make them less distracting.
And therefore, comments can easily become outdated.
So I'm curious about your situation. Since you say that you like to give yourself useful context for "future you", what context does this process serve? Do you find it useful when working on a shared codebase with lots of other developers? Or is it something that only works well when there are few developers touching the code?
> And therefore, comments can easily become outdated.
I am firmly of the opinion that keeping the comments up to date is part of the job of the developer. And if they're not doing it, they're not doing their job. It's no different than taking the time to write code that does the right thing, expresses the intent of what it's trying to do, etc. And, when code is peer reviewed, not including/updating comments in places where they are important should be a reason to send the code back to the developer.
I feel the same way about automated testing. They're both (testing and comments) way to make our code better; easier to understand, easier to maintain, more likely to be correct, etc.
> I am firmly of the opinion that keeping the comments up to date is part of the job of the developer.
I see where this comes from, but practicality is a huge issue. Comments don't become obsolete just by laziness, but also because they are human targeted and can't easily be managed the same way code is.
For instance if you comment on a function call to explain it's needed because of its side effects, when the function gets fixed and loses that side effect your comment becomes obsolete.
Will the person fixing the inner function go back to every single comment that vaguely references it's behaviour and fix them ? And do they also go to the one-up parent function to check the comments there ? If we're assuming large orgs with expansive code bases, it's just not realisitic to be dealing with all that prose and maintain consistency when what you're modifying can be mentioned anywhere is any tangential way.
> For instance if you comment on a function call to explain it's needed because of its side effects, when the function gets fixed and loses that side effect your comment becomes obsolete.
And if you have a function call in your code that doesn't look like it does anything and don't comment it, then you're doing it wrong.
And if the person who wrote `functionWithSideEffects` changes it to not have side effects anymore, and the places that call it for the side effects don't get updated then, once again, someone isn't doing their job.
Keeping comments up to date is no different than keeping code up to date, or tests up to date, or removing code that isn't needed anymore, or cleaning code up so it doesn't turn into spaghetti, or anything else we do as developers. Does it always get done? Of course not. But that doesn't mean it shouldn't get done.
> And if you have a function call in your code that doesn't look like it does anything and don't comment it, then you're doing it wrong.
We'll leave a comment, but it needs to be accepted that it will rot.
That's where personnally I'll explicitely date the comment to give the future dev a fighting chance to understand the context, if it's not directly linked to a ticket or some other documentation.
> And if the person who wrote `functionWithSideEffects` changes it to not have side effects anymore, and the places that call it for the side effects don't get updated then, once again, someone isn't doing their job.
It will work or not. In the meanwhile the side effect might not be useful anymore and become a useless call, or it might actually be doing something else that is now a primary effect. Hopefully there will be tests or external checks to validate the functionnality isn't broken.
It won't be ideal, but it's also a reality of a huge code base.
> Keeping comments up to date is no different than keeping code up to date,
The big difference being that at the end of the day comments are just comments, and they will always be a second class citizen relative to executable and parsed code. Sure in an ideal world we could ask people to treat them as critical, but short of having an actual organization wide strict enforcement of it with successful detection of comments that haven't been properly updated,
it would unprofessional to ignore the reality of it.
For code we have static analysis, dynamic analysis, white and black box tests, and user feedback. Comments won't have that level of scrutiny, so accepting that fact and treating them accordingly feels logical to me.
> It will work or not. In the meanwhile the side effect might not be useful anymore and become a useless call, or it might actually be doing something else that is now a primary effect. Hopefully there will be tests or external checks to validate the functionnality isn't broken.
If I have a Function_A that calls Function_B because it needs something Function_B does...
- If Function_A no longer needs that side effect, then Function_A should be updated to reflect that
- If Function_B no longer implements that side effect, then changing it has broken Function_A (and either B needs to be put back the way it was, or A needs to be updated to not rely on B doing it)
Both of those alternatives result in Function_A needing to be updated if it's no longer relying on Function_B doing the thing it was relying on it for. As such, any comment discussing that reliance can/should be changed when the code is changed.
Is there some other alternative that I'm not thinking of? Can you provide a concrete example, because I'm not following you.
> Comments won't have that level of scrutiny, so accepting that fact and treating them accordingly feels logical to me.
When I go into code, especially code with lots of relationships between them (large parent/child hierarchy, etc), it can be hard to understand what the code is doing. Comments make that understanding faster. They can be a difference of hours pouring through code. Even just a comment at the top of a file indicating what the code/class in the file is for (it's purpose for existing) and what other classes it's directly related to / uses can be a HUGE speed gain. The idea of not bothering to include that information because someone can't be bothered to do a good job keeping it up to date is just... confusing to me.
Function_A needs a connection to some file server, and for system specific reasons it wants it to have no timeout. For that it calls Function_B that is targeted to batch processing boiler plate, but also extends file server time outs. Function_A isn't a batch, but will still rely on Function_B for that side effect, with some comment on that.
One day the org upgrades its infra, and file server connections radically change but they take care of preserving compatibility. But no timeouts anymore, setting them do nothing.
They have the choice to go through the hundreds of instances where Function_B was called, look at the use case, and update it, though dozens of MR throughout the whole organization. Most of it probably on code that doesn't belong to the team making the file server change.
Or they can get rid of the timeout management in Function_B, alert the org of the change and request each team to deal with it on their own terms, and call it a day. Function_A will continue calling Function_B, and perhaps the new system timeouts are irrelevant, or perhaps new optimization options were added, and it happens that Function_B sets the right flags for Function_A to work in the best conditions.
The reasons to call Function_B will have either disappeared or changed, but the code will continue working, and at some point the responsible team might want to update the comments to reflect that, but it won't be a priority.
> understand what the code is doing
To me you're looking for design documents, not code comments.
I feel your pain, while also seeing no real good solution to understanding really fast a complicated and huge project. Comments can sure helps, the same way they can also be deceptive and send new devs into spirals.
I see it as a tradeoff between optimizing for new devs accessibility and pay the price in daily development and maintenance time, or having newcomers spend a lot of time upfront in exchange for more velocity for the existing members.
I personally tend to prefer the latter orgs, and find the code quality to actually be much better. It's usually a sign the org isn't shuffling or pumping new devs here and there every thursday, and people get to spend the time to understand the code base as it actually works, without needing to take too many shortcuts (I wouldn't see asking for an existing member to walk through the code as a shortcut btw)
I think color schemes that make comments nearly invisible are just bad. Visual Studio's default color schemes have it right. Comments are not treated as lesser than anything else.
As long as they aren't being placed every couple of lines they shouldn't really be a nuisance when reading through code.
And to me not updating the comments is the same as not updating the name of a variable when its purpose changes. The compiler doesn't care that you didn't update the name, but people reading the code do.
Also when it comes to "future you", you basically should think of yourself in the future as a different person. Because unless you are constantly working with the same bits of code, you will forget details and possibly even the high-level.
Yes, completely agree. Also, too many comments make it difficult to see what is in a class/function. If the comments make a class/function that would otherwise fit on one screen no longer fit on one screen there is a readability cost to this.
I wish they would put the comments before the function name in python, as otherwise the useful code is separated by useless verbiage. I also wish comments would include examples of the shape and dtype of inputs and outputs.
Collapsing/hiding comments should be a required feature in editors.
In Leo[1], you can make nodes out of them and just hide them. If Emacs weren't so good, I'd be using Leo. Similar power when it comes to extensibility, but extended via Python, not elisp.
Related anecdote: yesterday I was on a code portion of a personal project with a "Is this really useful?" comment on a line that seemed it could easily be removed. I tried to use the newer and cleaner class instead and the particular old way was indeed needed. So I appended a "=> yes!" to the existing comment as well. I'm glad my former self documented the interrogation.
At work, especially on bugfix, I often write a one or two lines comment with the ticket issue number over a non-obvious change.
It was pretty common say 25 years ago when you would be developing in a terminal. When you were limited in the number of lines displayed, it sometimes made it easier to follow the code when functions and control structures were large.
I know I had coworkers using brief configured to do that.
In 2000 years, I wouldn't be surprised if no contemporary television managed to survive.
Maybe most everything doesn't deserve to survive. Future humans will be busy enough living their lives, to learn an ever growing history of long dead ancestors. For them, it'll be mildly interesting to know that something was invented one thousand or ten thousand or a hundred thousand years ago, maybe the name of a chosen few relevant persons that first did something. But a complete record of everything that ever happened? I don't think so.
Most TV and movies feel horriby dated in a few decades.
Actually, I watch TV and movies done now that seem horribly dated.
I remember watching stuff during the pandemic with allusions to distancing or masking and thinking "I'm going to have to explain this to my grandchildren."
Whatever the reason, it's not so far fetched to assume the brightest are the first to leave. Or maybe the bravest, the most confident... I don't know. But better anyway.
I've had a very hard time getting my current job. No doubt ageism was a reason, combined with some years of self-employment that recruiters can't see as a anything but a suspicious hole. Still 40 is not old, wait one or two decades to worry.
Not sure if removing experience would have helped. After all, qualifications on nearly-extinct tech was an advantage in this case.
My problem is that I almost always get hired when I can talk with the technical lead. But I get filtered out before that step, like dozens of times past year.
Ambrinol is really disgusting (source: I have a small sample) and only makes sense mixed with the very nice ambroxide (IIRC, ambroxan is a commercial moniker for it).
There's a curious evolution about abroxan's rep. If I'm not mistaken it was Dior that first used the name instead of ambergris in the publicity materials. I guess they were trying to avoid the "they kill the poor whales to make fucking perfumes". But they ended with the "I can't stand that synthetic ambroxan crap, I must be allergic and everybody's wearing Sauvage now".
New perfumes use some other bullshit names like "driftwood", "marine notes" or just "amber" (a very different stuff).
But when it's some famous "difficult" person like Jobs or Gates, or in fiction like Doctor House, the version of them that we see is idealized.
Actually this is the exact counterpoint of TFA: using the inexistent genius as an excuse for the trade-off. Imitating the genius is more difficult than just being a jerk.
House is an interesting example. He wasn't an asshole because of his genius. He was like that because of chronic pain. And I actually have experienced that myself due to degenerative disc disorder. It is definitely not something you want to emulate. It is actually pretty terrible feeling like your emotions happen only in extremes due to reasons you can't do anything about, being able to step outside of yourself after the fact and see that you are needlessly hurting people you care about, but even knowing that, you can't stop it from happening in the moment.
This is outrageous and now it's a political talking point for the right, because the left uses it as a matter of "activism" from the "grassroot" movements that celebrate their spoils, at the same time they deny the problem exists at all from their ministries.
But let me remind you: from 2011 to 2018 Spain was NOT governed by the left, but by the Partido Popular with this guy as prime minister:
This moron didn't move a finger to solve the problem, that was already a thing. That's how things work over here: unless there's a massive public outrage, politicians do nothing.
What's not so useful: mandatory comments. A public API should be thoroughly documented, but some shops insist on writing comments for every function in the code, even private ones and even if its purpose is so obvious that the comment just rephrases its name. This practice is not only a waste of time, but also insensitizes you about comments and teach you to ignore them.
Other wasteful comments are added by some tools. I hate the one that marks every loop wiht a //for or //try comment.
reply