Why Not Comments(buttondown.com) |
Why Not Comments(buttondown.com) |
Oftentimes, the reason for that is that 20 years ago stuff like Doctrine, Liquibase or whatever just didn't exist. You know, the time when PHP developers shipped straight mysql_query calls with direct interpolation of $_GET, and most "enterprise" Java application came with a ton of SQL scripts and a dedicated multi page UPGRADE file explaining in which order you had to run the schema migrations, reboot systems, run manual migration scripts and whatnot to get an upgrade done. Some times, upgrades could literally take days.
Naturally, people invented their own stuff to make stuff just suck a little bit less, and it got more and more used in a company, only ever extended in functionality... the dreaded "corpname-utils" JAR dependency (if you're really unlucky, the JAR having been semi-restored from a half-broken decompile because the sources got lost along the way) or util.php that just got copied over from project to project. And that's how you end up in 2024, still maintaining some ORM that has its origins in Perl code written in the 90s by someone deceased in the '00s. (Yes, I've been there, although not that bad)
When commits are rebased, the log message must be revisited and revised. Changes can disappear on rebasing; e.g. when a change goes into a baseline in which someone else made some of the exact same changes in an earlier commit, so that the delta to the new parent is a smaller patch. In my experience, commit messages stay relevant under most rebasing.
Comments are (largely) an obsolete version of version control log messages.
In the 1980s, there was a transitional practice: write log messages, but interpolate them into the checked out code with the RCS $Log$ thing. This was horrible; it practically begs for merge conflicts. It was understandable why; version control systems were not ubiquitous, let alone decentralized. You were not getting anyone's RCS ",v" file or whatever.
Today, we would be a few decades past all that now. No $Log$ and few comments.
Mainly, the comments that make sense today are ones which drive automatic API documentation. It would not be reasonable to reconstruct that out of the git history. These API comments must be carefully structured so the documentation system can parse them, and must be rigorously maintained up-to-date when the API changes.
I could easily imagine somebody refactoring code to an obviously better version, finding out it doesn’t work for subtle reasons, running got blame and cursing the person who left that information in a commit message instead of a comment.
If that obvious incorrect way happens to match what you're thinking of doing, then that kind of why-not documentation will help.
Warning future developers not to make certain changes is indeed something that should go in a comment. We can make a short comment like, /* if you think you can rewrite this in a simpler way, read commit df037acb first */
There are unfortunate situations when things have to be changed in multiple places together; you must not forget all of them. That deserves comments.
If you have an enumeration that has to pack into 3 bits, there should be a comment warning not to add more elements than eight without increasing the number of bits; especially if there is no compile time assertion for it.
What’s the advantage?
In my first job, my older colleagues, most of them now managers, had managed to write their own library. It included its own timezone management, a wrapper o top of DEC's OSF/1 AXP concurrency primitives, a realtime memory-mapped database format, a compiler that run not on files but in expressions stored in an Oracle databse, and even their own CORBA-like object sharing over TCP/IP.
These people were wizards, and probably did a lot of stuff just to show their coding prowess, but a decade later when I joined that company most of the younger programmers did not dare to touch that code. I had to do that when the software was being deployed in Brazil, where nobody had expected how DST changes in the south hemisphere.
Sadly I am talking about something written in Perl (blessed with ORMs since at least 2001) around the early-mid 2010s. Not a single reason it should have been written. The only thing it gave us over well established Perl ORMs were code that no-one understood, no support for that code, and a panoply of infuriating bugs that constantly broke production.
For instance, you might write something like:
# I used a bubble sort instead of a quick sort here because
# the constraint above this guarantees there will never be
# more than 5 items, so it's faster to use the naive
# algorithm than to implement a more complex algorithm that
# involves more branching.
# Normally we'd do X, but that broke customer Y's use case
# based on their interpretation of our API docs which we
# had kind of messed up. So now we do Y because it works
# under both interpretations, at least until we can get
# them to upgrade.
Likewise, the title "World's longest DJ set" was confusing, because most people will assume that the compound word is "DJ-set". But if you read the whole article, then you realize that a python snake fell on the mixing board and accidentally mixed some tunes. So the compound word was actually "longest-DJ" -- a 2.5 meter python.
We should all consider using hyphens for all compound words.
We do use hyphens in English. Well, some of the time, and some of us. I could be wrong, but I do feel that, given my age and also my readings of older texts, that the use of hyphens in this way has become less common, and that this was much more common decades ago to avoid ambiguity.
Because the article is a rebuttal to those who oppose writing comments (that is where "why not comments" means "why you shouldn't write comments") where the main argument is that you should write "why not" comments (that is "why not comments" means write comments explaining why you didn't do something or do something a certain way).
I feel like I’m getting off the self-documenting code ride. In our own codebase we rely way too much on “descriptive names”. Like full-on sentence-names. And is the code self-documenting? Often not. You indeed cannot describe three or more axes of concerns in one name.
Do comments go stale? Well why does it? Too loose code reviews? Pull requests that have fifty lines of diff noise that you glaze over? We have the tools to do better on that front than some years ago at least.
It’s a joy to find a corner of the code base where things are documented with regular sentences. Compared to having to puzzle through five function call layers.
[1] But yeah, really. But also: sometimes also in comments. Sometimes both.
Ideally the future user would trace the git blame back to the original commit of they really had questions.
A long comment is really helpful sometimes though. I like to put ascii truth tables for complex boolean logic, both to ensure I cover all cases when writing the code (tests, too) and to make it easier for future me to understand what's going on at a glance.
def fetch_data(comment_id):
Args:
- comment_id: The id of the comment to fetch.
Returns: The comment data
data = fetchCommentData()
I worked on such project in my first job and I cared a lot about my commit messages, and changelogs.
On the other hand, in fast paced corporate development I barely ever see someone make commit messages like this. Even PR titles often leave a lot to be desired.
Who is arguing this? Usually, if I'm adding a comment on why something is done a particular way, it's something that is going to take at least a full sentence to explain if not a whole paragraph.
Sure people can tell what the code is doing over a file but comments could definitely add a little more context of what the code is _for_.
It seems only to be a thing with Jupyter notebooks, and even there it mostly describes the results and not the code.
It makes it way easier to send these into Claude (it seems, at least). I hope they introduce a semantic/vibes search too as I can never remember what I name my classes and functions...
The problem with comments is that they can become stale, and it's often possible to self-document or write simpler code that causes less surprise. But of course, it's totally fine to put comments.
And I think comments should be mandatory for interfaces functions/types unless their behavior is obvious. I don't want to read the code to understand what a function does, or what invariant a class maintains. And if it's too complex to document in a few lines, probably this isn't the right interface. But apparently, this isn't obvious for everybody. In my company, most of the code isn't documented.
I nearly exploded trying to grok this
Or you know, you could have just used a hyphen instead of clickbaiting.
I admire the honesty, but will continue to phrase these "why not" comments as insincere TODOs.
"A junior engineer writes comments that explain what the code does. A mid-level engineer writes comments that explain why the code does what it does. A senior engineer writes comments that explain why the code isn't written in another way."
(except punchier, of course. I'm not doing the quip justice here)
Exactly! I have written code that required comments five times as long as the code itself to defend the code against well meaning refactoring by people who did not understand the code, the domain, or the care needed to handle large dynamic ranges.
I have also written substantial functions with no comments at all because it was possible and practical to name the function and all the variables so that the meaning was clear.
It's fun and enlightening to go ham on any particular style/framework/philosophy, but actually living by dogma in prod gets kinda dangerous and imo is counter to the role of a senior+ engineer
I have regretted following that lesson ever since.
So, less comments wins out, but faced with a code base without comments you have to inspect it to tell the difference between a beautifully crafted piece of brilliance or a totally flaky codebase written by a bunch of newbie hacks.
This is a common experience when I use a new language or framework. At the start I comment a lot of things because I think it's useful for future me, but as I learn more I realize that many of the comments are redundant so I end up removing them.
If it's not answering why or at least providing a very concise how to very verbose code, then it's just adding noise
And C-level engineers write a comment "X hours have been wasted on refactoring this code. Should you decide following the example of your priors, please increment this counter."
Sometimes, even what appears to be an utter hack job actually is the best you're gonna get.
I'm apologising because the code isn't obvious, or the language not sufficiently expressive, or the good-idea-at-the-time no longer is. Ideally I wouldn't need to write many comments, but I often find myself sorry things are not simpler.
You are right in spirit to say sorry when the code cannot be self-explainatory, but consider that sometimes even if the code is self explainatory, comments can help your reader to see the grand picture faster or to avoid interpersonal ambiguity by allowing you to use two different ways of phrasing a thing.
Cursor cursor = getCursor(); // Cursor. class User {
public String getName() { ... }
}
Somethings I include brief explanations or links to a particular piece of hard-to-find documentation.
I suggest providing that sort of high-level decision information in a separate design document. This sort of documentation is written before the code and is presented/discussed with management and peers.
That is how it was done at a couple of companies I worked at and it was very effective. Naturally, this was done at the feature level, not on a function to function basis.
The nice thing about comments is that they're in the code. You can't update the code without at least looking at them; that's more visibilty than you'll get from anything else.
Alternatively, if your org or reach for this feature is so large that you need to communicate and decide its internals with a lot of people and as such require something like a design document, then you've already failed and you have way too-many cooks in your kitchen. Design by committee is always doomed to failure.
Thirdly... if you need a design document to communicate your feature to "management" then that means you don't have autonomy to design this feature as an expert, and again, you have too many "fingers" in your pie.
Does this mean you should go into a basement and design your feature like a hermit? No, but a design document shouldn't be your answer, it should be a better team and process around you, as well as a clear business specification.
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.
DEAR MAINTAINER:
This code is the way it is because of <reasons go here>.
Once you are done trying to 'fix' this, and have realised what a terrible
mistake that was, please increment the counter as a warning to the next
person:
total_hours_wasted_here = n
I one time wrote this fairly elaborate SQL generation thing that required pretty liberal use of recursion in order to fulfill all the requirements. It ended up being a lot of mutual recursion and the code was admittedly kind of messy but it was a necessary evil to do everything asked of me.
A more senior engineer ended up taking over the codebase, "fixed" all my code to be this iterative thing, made a point to try and lecture me about why recursion is bad in an email, only for his code to not actually do everything required and him reinventing effectively everything I did with recursion.
In fairness, he did actually apologize to me for some of the comments he made, but if I had thought about putting this comment on the top maybe we could have avoided the whole thing.
It's a problem if you're overflowing the stack, of course, but otherwise…
This especially applies to your own code that you write and still have to maintain 5, 10, 15 years later. Just the other day I was reviewing a coworker's new code and thought "why choose to do it this way?" when the reason was 10 lines up where I did it the same way, 8 years ago. She was following the cardinal rule of maintenance - make the code look like the existing code.
Comment on whatever would be surprising when you read the code.
When I write code, a voice in the back of my head constantly asks “will I understand this code later?”. (People who just instinctively answer ‘yes’ every time are arrogant and often wrong.) Whenever the answer is ‘not sure’, the next obvious question is “why not?”. Answering that question leads you directly to what you need to write in your comment.
Sometimes the answer is “because the reader of the code might wonder why I didn't write it another way”, and that's the special case this article covers. But sometimes the answer is “because it's not obvious how it works or why it's correct” and that clearly requires a different type of comment.
My driving principle in the same vein is "where do I have to look when/if this doesn't behave as expected?" - if the answer is not in the docs (wiki -> package/module -> file -> class -> function / method) or is otherwise > 10 lines away, it gets an inline comment (or the docs are updated). Usually this happens when chopping up strings or during intermediate navigation steps over an odd data structure.
Identifiers can go a _long_ way, but not _all_ the way. I personally am a fan of requiring documentation on any public methods or variables/fields/parameters (using jsdocs/xmldoc/etc). Having a good name for the method is important, but having to write a quick blurb about what it does helps to make it even clearer, and more importantly, points out obvious flaws:
* Often even the first sentence will cause you to realize there's a better name for the method
* If you start using "and" in the description, it is a good indication that the method does too much and can be broken down in a more logical way
People often think properties are so clear they don't need docs, then write things like:
/** The API key */
string ApiKey;
This is stuff that as the original author of the code you know and can write in a minute or two, but as a newcomer -- whether modifying it, using it, or just parachuted in to fix a bug years later -- could take _hours_ to figure out.
Another twist on this is to put in a debug logging statement which triggers when the inputs are much larger than the original design constraints.
It's roughly the same message to a future-developer, but they might find it much sooner, short-circuiting even more diagnostic and debugging time.
Your comment is super obvious, in hindsight, but I never thought to do something like this, usually at past places of work we've just agreed to make a comment on things we need to reconsider later and hopefully we remember about that comment when things go downhill!
For example, if the slowness of the method depends on non-trivial aspects of the input, or if the performance problem in production comes from someone calling your method too many times on (individually) reasonable chunks of data.
The "et" in "etc" means "and", so you have that already.
Using a debug log-level helps prevent that problem from occurring in production, while still making it visible to developers that have more logging enabled in their dev/test environments.
I know most people don't like it, and that is fine, they can deal with it! I they don't want to see my comments, they can remove them from their version of my code with a script, and if my co-workers and boss don't like them they can remove them in a code review! However, I can say that I enjoy reading my old code way more than I enjoy reading other's code which have zero comments. I work in Python, so a lot of the simple non-algorithm code (boilerplate stuff for apps, like flask APIs for example) is mostly "self-documenting" since the old saying goes, "write some pseudo-code and 95% of the time it runs in Python." The most important comments are sometimes on the boilerplate stuff because that's where a lot of changes happen versus the algorithms where I find there is a lot more wholesale rewriting in my industry.
I will always love comments and doc comments!
If a piece of code is weird, or slow, or you'd say "yeah, it's kinda janky" when describing to somebody, I usually write a comment about it. Especially if I've changed it before; to document some case that didn't work, or I fixed, or whatever.
When you operate on this basis, superfluous comments just melt away, and you typically end up documenting 'why' only when it's really necessary.
Try it out in your own codebase for a month and see how it feels :)
You can't have functional code for what isn't done, so that's some information you can't express in code.
Furthermore, a major problem with comments is that you can't debug or test them. There are many tools that can analyze code, static or runtime, but because comments are just free text, you can't do much besides spellchecking. Also it is common to forget to update comments, and with the lack of testing, in the end, you get lies.
But here, the only maintenance these comment need is to remove them if they stop being relevant. For example because you finally did the thing you said you wouldn't do, or just scrapped the part. Very low effort, also rather easy to spot, since if you see a thing being done with an explanation on why it is not done, it means someone forgot.
It is also worthwhile because as programs grow, they tend to do more, and "not" assumption may no longer hold (there used to be 4 parameters, now there are 10000...), meaning it is something you should check.
A lot of slow code comes from an assumption that N will be small, and N ends up being big. By the way, that's why I favor using the lowest O(n) algorithm that is reasonable even if it is overkill and slower on small sets. Because one day, it may not be. If for some reason, using a low O(n) algorithm is problematic, for example because the code is too complex or the slowdown on smaller sets too great, then comes the "why not" comment.
Then I realized that my languages will never be perfect, and having comments is an essential escape hatch. I was wrong and I changed my mind.
Also, 99.9% of languages have comments:
I've been in this exact situation quite a few times — use a bad algorithm because your n is low. However, instead of commenting, I did something like this instead:
function doStuff(items: Item[]) {
if (items.length > 50) {
logger.warn("there's too much stuff, this processing is O(n^2)!");
}
// ... do stuff
}Wow, someone actually suggested that?! Do people write whole programs like this?
My biggest headache right now has been getting high-throughput with SQL and as such I've had to do a lot of non-obvious things with batching and non-blocking IO in Java to get the performance I really need, and as such a of the "obvious" solutions don't work (at least with a reasonable amount of memory). Consequently I've been pretty liberally commenting large segments of my code so that someone doesn't come in and start bitching about how "bad" my code is [1], "fix" it, and then make everything worse by rewriting it in a more naive way that ends up not fulfilling the requirements.
[1] I have since stopped doing this, but I'm certainly guilty of doing this in the past.
There's often a fairly small kernel of very dense code that abstracts away a bunch of complexity. That code tends to have well north of a 1:1 comment to code ratio, discussing invariants, expectations, which corner cases need special handling and which ones are solved through the overall structure, etc.
Then there's a bunch of code that build on that kernel, that is as close to purely declarative as possible, and aims for that "self-documenting code that requires no comments" ideal.
Finally, there's the business logic-y code that just can't be meaningfully abstracted and is sometimes non-obvious. Comments here are much more erratic and often point at JIRA tickets, or other such things.
- URL of documentation for a complex feature
- URL with a dashboard with telemetry
- URL of a monitor which checks if the given feature, CI job, GitHub action etc. works correctly.
In a big project, figuring this stuff out is not trivial, requires a lot of searching with proper search terms and/or asking the proper knowledgeable person.
I find it weird that code is often so detached from everything non-code.
I often add comments to code as I decipher it, then remove them again when I figure things out.
No matter how efficient or eloquent, if you solve the wrong problem, you’re doing no one any good.
Solve the right problem efficiently, but in a way no others can understand, and you’ll flounder in a team. You will also never be able to collaborate or make larger work move faster.
Correct problem, clear writing, then logic.
But I suspect that there's a relationship: If their writing is hard to read, their code will be hard to read.
Every function (or procedure) starts with a comment block. It first talks about the what and why. Then, a line for the inputs and another for the outputs. Next -- and this is done closer to the end of the writing -- I describe what it calls and what it is called by. The comment block optionally finishes with room for improvement.
The function itself probably has other comments. Usually for anything which is not blindingly obvious. Because I write code like a caveman, wherein only one thing happens on one line, most everything is quite clear. If there's anything weird or magical that has to happen, it gets a comment.
Elegance and cleverness is reserved for data structures, algorithms, and so on, rather than doing a lot of stuff in as few lines as possible. I do this for Future Me, who might be having a bad day, or for anyone who wants to adapt my code to something else.
One of the last steps in a finished program is going through and making sure that my comments match my code. I am a very boring kind of programmer.
In other words, the comment allows the author to reach into the future and co-debug with the reader, even if the author is no longer there.
People rarely touch what I write, but if they do, and they want to strip the comments out, thats totally fine with me, just don't ask me how it works after you do :P
He did not believe in comments, much. I think he thought he was commenting the hard stuff, mēh, I am unsure.
It has led me into strong opinions.
* Document every function. The function should make clear what the preconditions, preconditions, and the purpose are
* Docunebnt every file/code unit. Why it exists
* Document important loops like functions
* Document the easy stuff. It is not easy if unfamiliar
* Review the comments when working on code
This would have saved my company about thirty percent of my time.
The compiler does not verify comments, like it does code, so it is a burden. Bad programmers get another opportunity to sow chaos, I know. But one of the main purposes of code is communication with following humans, as well as controlling machines
Careful and thoughtful comments are a professional obligation IMO
Doesn't seem to be a problem here though because they're replacing macros by symbols that are known ahead of time.
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?
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.
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.
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.
You will read it in 3 months and cry in despair "But why, my past self, why is it needed?!" :-)
Oh god, that's horrible, what kind of tool does that?!
I know I had coworkers using brief configured to do that.
This is so undervalued when maintaining an older codebase. Please, for the sanity of those who come after you - make the code look like the existing code.
I think it's a great rule of thumb... but there are exceptions.
For example, Funnily enough I was reviewing some code just today written by someone else and that I'm going to be asked to expand on or maintain. It looks like this:
var example1 = Object;
var example2 = Object;
var example3 = Object;
...
var example147 = Object;
var tempExample1 = <some object instantiation>;
var tempExample2 = <some object instantiation>;
var tempExample3 = <some object instantiation>;
...
var tempExample147 = <some object instantiation>;
The reason it looks like this is because the original developer copied the examples from the developer technical documentation for what they were doing verbatim; this documentation only had one variable so the numbering was the way to get multiple variables. Knowing this system, they didn't have to do that, they could have very easily assigned meaningful names for all of this. (To be fair, the original developer isn't a developer but a consultant business analysist saying, "Oh yeah, I can do that!" to the client.... billing all the way).
I can tell you with great certainty and righteousness: I'm not going to make my code look like the existing code. I may well do some refactoring to make the existing code vaguely scrutable.
I appreciate that what I'm describing is an extreme case and not really what you or parent comments really were addressing. I just stop to point out that what you describe is a rule of thumb... a good one... but one nonetheless. And, as an absolute rule of thumb about rules of thumb, there are no absolute rules of thumb. Ultimately, experience and judgement do matter when approaching the development of new code or decades old code.
The problem with unit test as documentation is that over time they end up reflecting the same misconceptions that the code has. Someone does a refactor, misunderstands how the original code works, and "fixes" the unit tests to pass. Now you have tests that lie just like comments can lie.
By contrast, I have really never seen truly self documenting code. The comments may be up to date by virtue of not existing, but the end result is just more confusing. YMMV
It was all great until you got here. This is a big red flag for me for a teammate.
Half the time I start by just writing comments explaining what I'm about to try and do, then I go back and add comments about how things did not go as expected, and what I had to do to get it to actually work. Super helpful 5 weeks later when I have to actually see it again.
You start with comments of how you want things to work, and fill in the code. It's a perfect combination of why/how and communicates to the next developer the high level thought process behind the code perfectly.
Interface expresses “what the function does” while the implementation expresses “how it’s done with what tradeoffs”.
Bonus, in the future, if performance ever does become a problem, you swap in the new optimized implementation behind the existing interface.
When you see a call to an interface, you don't know what the code does concretely, you only know what it is supposed to do. The actual implementation and how it ties to the interface may by in a completely different place. It is one of my biggest source of headaches when debugging code.
Interfaces are useful, the strategy pattern is useful, but overuse is harmful. My idea is to not use an abstraction unless I know I am going to need it. For example, let's say I need to decode video, and I have a hardware decoder and a software decoder. Here, an abstraction make sense, as I know the software decoder will be prohibitively slow one some platforms, and the hardware decoder won't always be supported. But if the optimized version is sufficiently better so that it makes the old version obsolete, just change the code.
And if I don't know if I will need to change strategies later, I just write the first strategy, and if it calls for an interface later, only then I will do the abstraction.
I suppose if you make the refer nces fancy enough you wind up reinventing rst
func uglyHackForCombiningTwoThings() {
// Do whatever ugly thing you want to do
}Unfortunately, short names do not indicate that someone did know what they were doing! =)
In reality, of course, software development is about getting large groups of people in-sync as to problem, solution, and implementation. That takes lots and lots of communication. Ambiguous, messy people-to-people stuff, without The Right Solution to contents or wording. Because there's a bias towards thinking of the Program as Reality, it never occurs to such developers that an identifier can become just as outdated or wrong as a comment, and in fact it is easier to correct a comment than to globally rename identifiers, or that a 20-word comment carries vastly more information and nuance than a 20-character function name, or that trying to shoehorn information important to developers into a language used to tell _computers_ how to function is worse than trying to drop assembly language into a SQL query.
I realize you're trying to explain a way of thinking that you don't actually share—but this doesn't make sense to me either.
Computers parse identifiers in only the simplest sense—they care if two identifiers are identical to each other or different. So, any identifier longer than one or two characters is in some sense a comment, because everything longer the minimum necessary to make the identifier unique is ignored. They're literally stripped from the output if you don't retain debug symbols or use a minifier (depending on the type of language).
To me, the suggestion seems so incredibly bad that it leaves me wondering about the headspace of someone who would suggest that. Is it somehow less bad than it seems?
1) empirical measurement compared to a large number of alternatives ... the empirical measurement or study is never mentioned: because they do not exist
2) the best practice is valid in all measurements and criteria of comparison: performance, elegance, simplicity, correctness
3) since there is no data, the reasons for why the practice was designated best are rarely even explained
4) nor are the circumstances or individual or source of "best practice" detailed
5) it will always be the best practice: it is the BEST! It CANNOT be improved.
So we have an unsubstantiated, unargued, unsourced, non-authoritative, exaggerated declaration in virtually every case of "best practice"
If you didn't back that documentation up with some tests to reflect the necessity of that complexity, this is an avoidable tragedy. But if the junior then comes in and deletes your tests because they don't pass, that's a firin'.
That is things like cases it doesn't support, or weird results in some cases.
One example is a shop I worked many years ago that had a function which did time conversion on date times without adjusting the date portion. Obviously, objectively, wrong.
However the callers to this function expected this errant behavior. Actually changing it to behave correctly would require a coordinated change. Putting that comment in place prevents a new hire from going "oh this is obviously wrong!" and fixing it, causing an outage.
If you need to communicate your design to a lot of people, that's probably because a lot of people are depending on the output of your work, and they want to make sure it suits their needs. That's not design by committee—that's just designing something that will be widely used.
The process led to not only better designs, but also better visibility for all stakeholders, from technical leads to individual contributors.
I'm talking about products that shipped on billions of devices, products that you have most certainly used. It worked.
void vendorReturnsDataInInvalidFormatAndButShouldBeResolvedByVendorOpenTicketXYZ_123ExpectedResolutionQ42024(String input) {}
Having documentation in your repo describing high-level architecture choices and peculiar quirks for future maintainers is nice, sure, but I think that's a separate document with different goals and relatively little overlap. It shouldn't be organized by feature, for starters.
Also, if the remarks in that document are granular enough to exist as comments, why not just leave them as comments? Then they're more visible and more likely to remain up-to-date.
Note that I distinguish comments from API documentation even though they are often both in the same code and use the same comment syntax.
When you figure out something tricky, leave a comment.
Git commit messages are better than comments, because they tag the specific baseline of code where a decision was made, and you can write multiple paragraphs to explain something (including all the "why not"), without cluttering the program text.
The problem with comments is that they also pertain to a revision that existed around the time they were written, but they stick around, pointing to newer revisions, perhaps falsely. They add clutter. Unless you use a folding editor, comments can separate pieces of code so that you see a smaller window of the program.
One line of code can be touched by many, many commits. Each of those commits should have something to say about that, and all that talk cannot possibly be put into a giant, ever-growing comment next to that line of code. In regard to my previous point, a lot of that talk won't even be relevant to the current version of that line!
I've taken the view that the thing I'm developing is a git repo, not the source tree.
A source tarball is just something for building and deploying, not for development.
If someone wants to understand why something was done, they must use the repo, and not a source tarball. If they insist on just working with the source snapshot, but ask questions that are answerable in the git history, I cannot support them.
That said, git commit messages as a meaningful source of information aren’t for me, I prefer reading the code as a single pane of information. We alleviate concerns about doc strings and comments becoming out of sync with the code by just reviewing comment salience as part of standard code review.
Either way, I think there’s no wrong answers, if it works for you and your team then that’s good.
In my open source projects, I use GNU ChangeLog format in the log messages. This mentions every file that is touched, and every defined entity (function, type, macro, variable, ...). In a code review, while it would still be difficult to enforce the quality of what is written about these things in the comment due to subjective reasons, there are objective aspects to it. When reviewing, you can point out something like "you changed the initializer of global variable g_foo, but it's not mentioned in the commit message".
Sure, API comment headers can be enforced reviews. But those are not the comments this discussion is about (and elsewhere I identified these as necessary comments that can't be farmed out into the git log messages).
I do not think that helps much, in the general case
> The problem with comments is that they also pertain to a revision that existed around the time they were written, but they stick around,
Comments do require maintenance. It is part of professional practice
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.
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.
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 would be nice if they could be like footnotes, or boxed out-takes, that could be pushed to side notes. We have had the typography, even if it was just markdown with a rendered code reading mode.
Rich text code would create so many problems, too. You get locked into a special editor. You need special version control. Grepping becomes difficult. Diffs become difficult. You'd need a whole separate ecosystem, and for what? We have treesitter; we can already treat code like data.
As for the argument that it wastes time to update comments, I've never seen a codebase where the comments were so voluminous that it would be a significant burden to update them. Devs avoid updating comments because there is usually no penalty for doing so (boss doesn't call them on it, and the code still runs), and they think they've saved a few minutes when in fact they're just kicking the can down the road for the next dev who has to decipher the incorrect (or missing) comment.
And often for completely different reasons. Blithely assuming it's all about "lying" comments is totally unsupported by any evidence.
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)
- The code 'tells you' what it does
- The comment for the code tells you what the author intended it to do.
The gap between the two is where bugs can be found.
Not quite.
The comment for the code tells you what the author of the comment understood the code to do when hen wrote the comment.
I don't write what the code does or even what "I understand the code to do". I explain choices, especially ones that the next developer or my future self is likely to misunderstand when looking at the code.
I've always said coding is a cottage industry!
It's luckily rare for people to add wrong comments, though (and those who do should be publicly fustigated).
By the way, please never state something as it were the truth if you're not sure that it is. Saying "I think" is perfectly fine, and might save people days of investigation.
I've seen 64 character variable names
Names should be mnemonic. Reminding, not describing
There's vanishingly few cases where this extra logging statements will ever be a problem and they can all be handled autonomously if they ever are - but it will save everyone else a ton of time in deployment.
Re: busy, no because I only enable debug logging when I need it
Re: loops, I wrote a deduplicating logger, so if there are 200 identical messages from within a loop I see:
{event: "thing happened"}
{event: "thing happened",
duplicates: 100,
since: "2024-09-11T01:05:00Z",
reason: "count reached"}
I think it's important to log the first one immediately, just in case you want to alert on that message. It wouldn't do to wait for the other 99 before raising the alarm.
I wrap my loggers in deduplicators only when I'm about to hand them off to a loop. Otherwise it's the normal ones.
The point is there's a big difference between "we've got a problem, we need to add logging and redeploy to try and isolate it" versus "we might have a problem, bump the logging level up on that service to see what's going on" (which with the right system you can do without even restarting).
log.Debugf("Foo is: %#v", ...) //You think: this is probably filtering code log.Debugf("Foo without X is: %#v", ...)
If you're commenting about the code, do.
There's a huge difference in the value between one or the other.
Therefore, comments should only be used for things like psuedocode, or as help for fellow developers during dev.
Then, they should be removed once the code is done.
But yea, not a good idea.
If you can make your code more clear, so that comments aren't necessary to explain what it does or how it works, that is probably (but not always!) something you should do. But that doesn't mean you shouldn't have comments. At the very least there should be comments explaining why (or why not) things were done a certain way.
But of course you will have some individuals who think it is cooler not to, and they are probably the same people who think use after free bugs can be avoided by the shere willpower of the solo-male-genius that they are.
Good readable code removes the need for comments about what the code does, if the working of the code needs extra explanation then perhaps it is being too clever or overly terse, but there are other classes of comment that the code simply explaining itself can't cover.
Some of my comments cover why the code does what it does, perhaps linking it to a bigger picture. That could be as simple as a link to work ticket(s) which contain (or link to) all the pertinent details, though I prefer to include a few words of explanation too in case the code is separated from whatever system those work items are logged in.
Many comments state why things were not done another way. This can be very similar to “why the code does what it does” but can be more helpful for someone (perhaps your future self) who comes along later thinking about refactoring. These can be negative notes (“considered doing X instead, but that wouldn't work because Y or interaction with Z” – if Y and Z become irrelevant that future coder can consider the alternative, if not you've saved them some time and/or aided their understanding of the bigger picture), helpful notes for future improvement (“X would be more efficient, but more complex and we don't have time to properly test the refactor ATM” or “X would be more efficient but for current use patterns the difference would be too small to warrant spending the time” – the “but” parts are not always stated as they are usually pretty obvious). A comment can also highlight what was intended as a temporary solution to mitigate external problems (“extra work here to account for X not being trapped by Y, consider removing this once that external problem is fixed” or “because X should accept Y from us but currently doesn't”).
This is one of those blindspots devs have in that they believe their code to be good and obvious to everyone but in reality it is not even good and obvious to their future selves who will be the ones maintaining that code
That could be used to see how good a language is for specific tasks. If you need to write lots of comments, maybe you have the wrong language.
That and “those who actually use power are likely to be those who shouldn't have been given it”!
I did a survey once in about 3/4 of the comments were either wrong or useless. Examples:
//Add 1 to x
x+=1;
//Add 1 to x
x+=2;
//Seconds per normal day
x = 86400;
--
"Why not" comments are incredibly valuable except they suffer from explanatory decay as much as other comments.
The hope behind Intention Revealing Names is that the dissonance will be too great for the subsequent developers to ignore when they change the code.
Of course, that isn't always true.
x = 86400
x = 24 * 60 * 60
DAY_IN_SECONDS = 24 * 60 * 60> Examples:
> //Add 1 to x
> x+=1;
If 3/4ths of comments are like this, maybe show a sampling of public source code (e.g. from github) that shows how prevalent comments like this are in any real codebase.
I've been programming since 1982 and have never seen this type of "add 1 to x" comment in real code, outside chapter 1 of some intro to programming book.
I will als name each db table column in the correct order by its correct name right above that what decided the value.
// id
user_id = getUserId();
They serve as dividers.
using namespace std; // using namespace standardAnd, you definitely had little experience with under-documented code
Also: if the code and the comments appear to disagree, there is a reasonable likelihood that both are wrong in some way.
MINUTES_PER_HOUR = 60;
HOURS_PER_DAY = 24;
DAYS_PER_SECOND = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY
Naah.
DAYS_PER_SECOND = 1 / (SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY) ;
It happens occasionally, but it's usually a sign that I'm doing something wrong.
IMHO that rule can be generalized: Whenever you make rules for other devs, make sure that the assumptions on which those rules are based are true, lest you interfere with their work in a negative way.
RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs()
But one shouls be careful not to mentally think of this as a zero sum dichtomy, where you either have well named functions XOR you have comments, because in reality choosingn both is often the golden path to success.
The danger is of course that code that is totally obvious to you now will take far more time to become as obvious later, be it to your future self or to your psychopathic lunatic co-worker who knows where you live.
So very often code can be made more readable by adding comments, even if it is just saying the same thing with other words, just by reducing ambiguity. Comments can also bridge higher level concepts in a good way, e.g. by you explaining in a few lines how a component fits into a concept that is spread out over multiple files etc.
In the end code is text and like regular prosaic text you can both make it harder to understand by not mentioning things or by mentioning too many or the wrong things. This is why it is not irrelevant for programmers to be good and empathic communicators. Sure in the end readability doesn't matter to the computer, but it certainly matters to all people involved.
That's the only reason I can think of for writing those comments.
I agree.
> It is inexcusable.
I think it can be quite easily excused on grounds of triviality, though whether that's appropriate may depend on context.