For me, any code that I wrote more than 3 weeks, I forgot. That's why I comment the hell out of my code. The younger programmers have routinely told me "commented code means the code isn't very good." I chuckle and ignore them and wait for them to hit their mid-30s and older.
> Understood as senior: Communication skills matter most.
The reason people dismiss comments is usually that they or others around them aren't good at writing useful comments.
Especially when there are linter rules requiring comments you'll have something like def open_thing(x, y): and a comment, "defines a function that opens thing."
Yes, those are pointless. Often what's going on is a person is dumping their stream of consciousness into the comment field.
It takes practice to understand what a reader needs to know. You have to actually practice reading comments and thinking things through (another reason code review is important in your team) to get good at undertanding what you should write down.
All that said, if you truly hate commenting, at least build a habit of descriptive naming and exploiting your type system as fully as possible.
As opposed to telling the boss what you're going to do.
I actually think those comments are useful in two ways:
1. The process of writing a comment will help often help me rename the function/variables so e.g. “defines a function that opens thing” becomes something like “opens can_of_worms with the given instrument and restraints” for the method definition open_can_of_worms(instrument, restraints)
2. You can use variable/return value comments to further restrict the domain of values, e.g. non-null, positive or in the range 1-42 (arguably it would be better to express some of these in the type system, but that is a different discussion). These comments show up in my IDE when I try to call the code in a remote location, so I don’t have to guess or remember the constraints.
(edit formatting)
While I don't like comments that try to explain what code is doing (write better code), comments are very useful for annotating WHY code does what it does. They're also very useful for adding documentation references, code use gotchas and things that need to be addressed in the future.
I hear comment love very frequently from enterprise engineers working with 10+ year old Java codebases, but very infrequently from hackers working with young code bases in more concise languages (complex algorithms aside).
Where I work, I can expect my scalacode to be read by people who can barely write a line of it, and I routinely read typescript and go code while being totally inept at those.
I bless comments that are here to help the reader read, and I let those behind too where there's some specialists-only syntax.
Descriptive types, clear tests, and sensible variable names are much more effective strategies for making code understandable. Comments should be a last-resort stopgap.
Comments don't have to decay. Discipline is important. Culture is important. And yes, these have to be intentionally set and upheld.
If you set a culture of discipline around maintaining the comments with the code, and ensuring they are updated, then it's really not that hard to do it. If the developer doesn't remember to do it when making changes, then the code reviewer can catch it and enforce it.
And nothing really substitutes for an english language explanation of the "why" and the intention of a particular section of code. A good comment explaining why something was done a particular way, or what the code was intended to accomplish, can save hours of walking up and down call stacks. It's also something that cannot be communicated through unit tests, or even integration tests, a lot of the time. Those communicate the "what" and the "how" - not the "why".
These are things that are often completely outside your control.
> If you set a culture...
At most shops, you don't get to set the culture. About the only time you do is if you're a founder or early developer. Otherwise you have to fit into the existing culture, or attempt to find a company that better reflects what you want. Sure, it's not hopeless; you can likely influence to some extent, but your influence is usually limited.
> And nothing really substitutes for an english language explanation of the "why" and the intention of a particular section of code.
I do agree with this. Any code that can't be written in a self-documenting way absolutely must be commented. However, if you find the need to do this often, it might be a sign that you should focus more on code clarity and less on (likely premature) optimization, or perhaps consider if you're really using the right tool (language, framework, etc.) for the job at hand.
I will admit that I probably comment less than I should, but I feel like the average is way too verbose, and that enough comments are out of date and incorrect (often in very subtle ways) that it adds significantly to my overhead when trying to understand someone else's (or even my own) code.
To be equally brutally honest: right back at you. I would trust the quality of those I've worked with over those who believe in comments, any day of the week.
My point was simply that I started as a believer in comments when I was more junior, and became anti-comment through experience. So even if we believe senior people are more likely to be right than junior people (which I very much doubt, frankly), that tells us little about whether comments are good or not.
> If you set a culture of discipline around maintaining the comments with the code, and ensuring they are updated, then it's really not that hard to do it.
Human programmers have a limited discipline budget, and if you're spending it on keeping the comments up to date then you're not spending it on other things. Yes, you can use manual effort to keep code explanations up to date, just as you can use manual effort to ensure that you don't use memory after it's freed, or that your code is formatted consistently, or that the tests were run before a PR is merged. But you're better off automating those things and saving your manual effort for the things that can't be automated.
> And nothing really substitutes for an english language explanation of the "why" and the intention of a particular section of code.
Disagree; code can be much more precise and clear than English, that's its great advantage. As the saying goes, the code is for humans to understand, and only incidentally for the computer to execute. The whole point of coding declaratively is that the "why" is front and center and the "what"/"how" follows from that.
I've been writing Lisp off and on since late last century, so I know full well the value of declarative code. Preaching to the choir, there! But I can also report that every real program I've ever written (i.e., that had at least one user) needed significant non-declarative parts.
And for those non-declarative parts, you need the "why". Why is this call before that one? Why is this system call used? Why is this constant being passed to the call? And so on. (It's because when you run it on OS ${a} version ${b}, there's a bug in the ${c} library that requires us to force the initialization of the ${d} subsystem before it can ... true story.)
The declarative parts of your program don't require "why" comments, and that's great, but a corollary to that is the parts that can be written in a declarative style aren't the ones that require a "why". Building a DOM structure manually takes a lot of lines of code, but it's all still quite simple, and requires no explanation. Writing a trampoline necessitates a bunch of "why"s, and there's no way to just substitute a declaration for it (without pushing the whole mess somewhere else).
Code is first for humans to understand, and that requires comments, because humans speak English (or some other natural language), and no programming language is yet powerful enough to efficiently (in time or space) express everything that English can.
I've got a trampoline in my codebase to avoid a stack overflow. The why is the test that a certain repeated operation doesn't stack overflow.
There are a number of places where it could've been implemented with one technique or another, but there's no particular reason that the approach I've taken should be better or worse than one of the other options. If there was, I'd want to formalise that (e.g. if I'd chosen one approach because it performed better than another, I'd want a benchmark test that actually checked that).
This doesn't address the parent's criticism. Clear, precise code only tells you what the computer is doing. What it can never tell you is why the computer needs to do it exactly like that.
Software breaks in weird ways when pushed to the limits. The fixes for these edge cases are not always obvious and may not be something that can be replicated with testing.
Without comments, some cowboy can come along and think, "it's flushing a buffer here? that's dumb. <delete>" The change gets put in, passes testing, spends four months in production, when a bug report comes in from a customer complaining about an issue that they had three years ago.
Now someone has to spend a bunch of time figuring out the problem, QAing the fix, then getting it back into production. It's thousands of dollars that the company could have saved if only there was a comment about why that buffer flush was there.
You might think this is some crazy edge case, but it's not.
Reconstructing the original idea or meaning can often involve far more context than local variable and functioning naming can provide.
Do you never see code that has global side effects? Or that is written a particular way to take advantage of the hardware that it is running on? Or any other of the many ways that the intention and meaning of a piece of code within the codebase it exists in can be not immediately obvious?
The answer for modern languages and frameworks is "write pure functions."
>Or that is written a particular way to take advantage of the hardware that it is running on?
Move to service/helper/utility class for that particular hardware or with a name that clarifies it's for that particular hardware.
I find comments to be necessary very rarely. Atm looking at a codebase where they are made to cover up for a lack of desire to think.
Declarative means that we specify the "what", and the machine deduces the "how".
There is no room for "why", because our present-day machines do not require motivating argumentation in order to do our bidding. They either need the "what" or the "how", or whatever blend of the two that we find convenient.
We need the "why" in the documentation. Such as: why is this program written in the first place? The "why" is not in the code. When code is clear, it's just easy to understand its "what" or "how", never the "why". Unclear code obscures the "how" or "what", but clear code doesn't reveal "why".
Every "how" breaks down into smaller steps. Of course, those smaller steps have a "why" related to their role in relation to the other steps; that's not the "why" that I'm talking about here. Of course we know why we increment a loop counter when walking though an array: to get to the next element. If you start commenting that kind of why, you will soon be flogged by your team mates.
Agreed, code is much more precise than English. But precision is not the same thing as being meaningful and without context, precision is useless. Code generally sucks at context, which is why every programming language worth its salt has comments.
This is not always possible, and in those cases I also strongly prefer well written, concise comments explaining what is going on and why, ideally with a link to a reference/source which explains the background.
Some examples of method names:
- generateTreeToAllowPartitioningOfItems(...)
- getMatchingRegularizationPenaltyForSpecialCaseX(...)
- getShortTermRedisProxyCache(...)
- createNewPrefilledTemplateObjectForXYZ(...)
I hope this doesn't sound snarky. But more often than not comments do date in my experience (and they don't handle refactoring well), while (compiler-known) names are handled as 1st class citizens by the current IDEs and thus are corrected and updated anywhere.
In code reviews we usually aim for "low comment" density, the implementer shouldn't explain what or why he was doing, the reviewer has to understand just from the code (as it would happen if she/he has to maintain it later on). The review is "not good" or even fails if the reviewer doesn't understand why and what is happening. The outcome will in most cases be an improved design, not more comments.
(assuming, which you should always assume imho, that you left the company many years ago when this event occurs)
As a common feature of most higher-level languages is that they co-opt natural language terms (and also mathematical notation, which is an option in commenting) with the intent to increase clarity, can you show us an example where code is more clear than natural language in explaining both what it is doing and why?
If you are working in something like APL, I can see there might be a case...
I am not so much interested in the precision issue, as both code and language can be very precisely wrong or right.
You think humans are bad, try working with Lobster programmers, they get work done, but their coding style is just horrible (they use tabs).
They can. Just after correcting all the buffer overflows and before fixing all the use-after-frees. Then the comments can be consumed by all the other teams with the discipline and culture to avoid writing bugs for all time.
It does not follow from the possibility for error that a "significant" proportion of comments will necessarily be false. In my experience, that is most likely when an organization has commenting as a mandatory part of its process, which inevitably leads to most comments being trite, and some wrong. Outside of that, comments have not been a problem mainly because they are almost non-existent, even when the code could benefit from them.
I'd add; Comments should be saying _why_ this crazy method is here. You can always parse the code to figure out what it does. In a few months/years (depending on your memory) you will not remember _why_ this code was put in place.
My personal favorite comment style is to wrap a chunk of code in `#{` `#}` blocks and add a general comment of what that chunk of code is accomplishing. Sort of like an inline method.
I simply like comments for adding things like... so and so told me to do this... or simply documenting weird behavior or weird business logic.
Comments are for things like
1) explaining why this thing that looks wrong or dumb, really isn't. 2) explaining what method/function/class/whatever is suppose to do. Because code can be correct, understandable, and still wrong.
Comments don't get updated when the requirements for the code change, more often than not end up as misleading.
The only thing worth commenting are actual libraries that are maintained, and 'magic values'.
I couldn't agree more.
A while back I got in the habit of trying to write code for "me, six-months from now". So, if I think I can explain it to "future me", then I'm happy. Ever since I started doing that, I've been much happier with "past me"'s code.
In addition to comments (particularly around hard to grok code), I've also started trying to be as consistent as possible in code structure and naming schemes. This also helps a lot.
Meta comment: This is bullshit and has problems with this that and the other thing. But to fix that I'd have to refactor this other module and I'm not going to do that now. And the other thing I'm drawing a blank.
Meta comment2: I don't think the code needs to do this here. But I can't prove it right now.
Meta comment3: We absolutely need to do this exactly as it is. Because otherwise bad thing happens, which you probably won't see until it hits production.
Meta comment4: This function name isn't correct. But I can't think of a name that is better.
I used to worry about putting emotional blurbs in comments or commit messages, but I'm starting to see their value. A commit that starts "This ugly writing is to appease Roger, the editor obsessed with AP style" lets me know three things:
- Who asked for the change - The source of the content - The fact I disagree but still do it, so future me doesn't pick fights present me avoided
Of course, it could also mean "TODO: revert this commit the minute Roger retires."
On the other hand, on the rare occasion that I've commented or committed something based on emotions, I've always regretted it. Granted they never caused problems for me, just a source of internal embarrassment. Still a good enough reason to be thoughtful about what emotions you express.
This is the highest purpose that a comment can fulfill - telling why you are doing something that looks stupid.
When dealing with articulate code I often rename the same thing multiple time while I understand it better/clarify it's purpose. Also I love how naming protects the purpose of a variable or method, mentally speaking
Most such commits are never looked at again. But every other month or so, I come across a maintenance issue where I wonder about the context of something. In many such cases, I've saved multiple days of false starts or debugging. So it pays off in the long run even if it's only me gaining something from this. (Unlikely; we're a company of 80 developers).
Sometimes you have a choice of a clever way to do something, which saves a few lines and uses neat language tricks that you rarely use * , or just doing things the boring way. As long as the boring way is obvious enough, it's often the better choice.
* I'm looking at you, Ruby... :)
``` doesAThing() //does a thing ```
doesn't help anyone.
My rule: Code is for how, comment is for why.
Excellent. For interfaces, other code that uses the interface (perhaps even tests) can also help to document the "why".
Or you could sneak one more little if statement or some copy/paste in there to fix it instead, and add a little comment that says "If you modify this line, please verify that your change doesn't impact Line XXX of file FFFF as well." And then you're done in less than a day and have saved a huge amount of testing.
I've seen code from an otherwise highly capable developer that contained 1000+ LOC functions. When asked why he couldn't do a refactor the answer boiled down to fear. When the only real way to test the code is by physically running a machine through a number of scenarios, many of which are difficult at best to recreate, you become very reluctant to refactor or clean it up.
Like all problems, it's best to nip it in the bud before things get that far out of line.
Definitely useful in the case where it's near-to-impossible to DRY up something, though. Sadly, the limitations of an industrial C environment have led my code to contain a lot of annoying 'If you add something here, make sure to add it to X struct and Y function' comments.
That way, I can understand what is actually being done. And I can then re-analyze why I did the shortcuts to get to optimization.
But 99% of the time, we dont need to optimize. CPU/RAM is cheap. But those 1% of the times when you're going from N^2 to N^logN ... Welll.....
Thats what I get for trying to type it on a phone browser!