Isn’t commented code no longer considered a good idea in most companies?
I used to work for a bank and the policy is no comments unless absolutely necessary, because comments become out of date. Doxygen is the only real comments allowed.
I used to work for a bank and the policy is no comments unless absolutely necessary, because comments become out of date. Doxygen is the only real comments allowed.
I tend to treat them like a strange hybrid of a story with editor's notes.
Here's where we're going... but oh no! Something is in the way. We need this critical, but painful to acquire shovel.
If I anticipate even the slightest bit of refactoring around it, I'm noting what devilishness lead me down this path.
TLDR: anything that could be abstracted away/not exist, probably deserves comments on why it does... perhaps even how it could be removed.
And "profanity" in code is almost by definition a "Why"-type comment.
You don't get upset and leave a profane comment unless you did a deep dive and realized the code does something absurdly horrible that took you far too long to figure out.
// this shit implements fizzbuzz
fizzbuzz()This describes my profanity use in comments perfectly. I'll even increase the amount of profanity and "descriptive phrases" depending on the frustration level I peak at.
Fun fact: my profanity will always be formatted into proper, grammatically and contextually correct sentences. This seems counterintuitive.
I'm curious what kind of profanity other people use; whether anyone else has an oddly specific format or if it's more off the cuff. (fyi: edited to not be cussing on HN, there will be a 100% chance my first profanity will be :"f###ing bulls##t," this is usually enough. In more severe cases I'll generally add: "bloody h3ll," "raging dumpster fire," "dumbest s##t ever," "d#mnation! h#llfire!," and, when I've completely lost my s##t, "what in the actual f###ing s##t is this g##d##n f###ing bats##t f###ing insane s##tshow clusterf##k!"
It saves a lot of time down the road to know whether I got pissed, super pissed, pissed af, threw some random s##t, or "welp, it's 5 o'clock somewhere."
There have been cases where very slight changes in methodology completely fall apart - reasons varying. Timing, cache fit, and whatever else you may think of.
Jenkins is something I've been picking up lately, and the 'DSL' has a ridiculous number of quirks
Ie:
def drive
turn_ignition()
shift_gear()
press_accelerator()
end
def turn_ignition
… code
end
def shift_gear
…`def start_the_car_and_accelerate`
Any tester is going to need detailed information that is devopsy and cannot be expressed in pure code (Despite the claims spoken by the code-as-infrastructure tools).
There are also cases where I like to document the living shit out of my classes/functions if they are something that will be used by many other devs. Bash/unix functions are some of the most heavily-documented tools you will ever see. Try using 'man grep'.
There are more questions than "why" that can be answered by comments. There are also "What ifs" that you could anticipate. Many of those "what ifs" are almost certain to appear in certain circumstances, and I choose to drop a few breadcrumbs that can save the code maintainers a few weeks of their time rather than following a false lead.
The beauty of code comments is that they don't require some external tool. They are in the pudding with the code itself, where they can be found easily. Most IDEs allow you to collapse long comments and even fade comments into a light grey so they aren't distracting.
From this thread and work experience I know that the code commenters are losing our war and are pretty much defeated by the code aesthetics crowd - who insist code should be beautiful before being useful.
I disagree about the "how", at least for challenging to read sections of code. In these instances, it is not good to assume that everyone who is reading or modifying the code is an expert in the language or problem domain, so it's good to explain to them how code solves the problem.
Explaining how the code works is very different than explaining what the code is doing. For example, something like "This code takes input sets of timestamp data and uses a timestamp keyed hash map to bucketize them by n minute interval".
That is very different than explaining how at each step you look at each time stamp and bucketize it, then generate a new time stamp bucket key and add it to the hash map.
The first approach explains at a very high level what's happening technically so that the reader can more easily understand the operations needed to accomplish the objective.
def group_by_interval(timestamps, interval_duration)
# do the stuff
Code gets out of date as well, so let's just stop writing it altogether..
Actually, speaking as someone's who's been generally critical of the "get AI to write our PRs!" thing, having an AI attempt a quick sanity check of comments near where your edits are could maybe work well
but comments telling you one thing is happening when something else is happening is a problem, and i suppose it couldn't happen if the comments weren't there.
1. An odd business requirement (share the origin story)
2. It took research (summarize with links)
3. Multiple options were considered (justify decision)
4. Question in a code review (answer in a comment)
And the article on how/what/why in code: https://max.engineer/maintainable-code
- The code is not self describing for some reason (eg duffs device, complex math, non obvious cases, etc)
- The code is correct but it looks intuitively wrong. This comes up every few thousand lines for me, where some conditional looks redundant or twisted up for some reason - like maybe there’s weird choices to keep the borrow checker happy. I leave a note to myself because next time I read that code I’ll want to “fix” it.
- Internal function preconditions / invariants. Eg, “this method must only be called while the XXX mutex is held” / “this code can only be reached when YYY is true because <reason>”. Sometimes these checks can be cheaply expressed in assertions, but not always. And sometimes you need comments as well to describe the nuances of what’s going on.
Rereading my comment, maybe these are all examples of comments used to support code that’s not self describing. I’ve been programming for about 30 years now. I don’t think self describing code is always possible or desirable. I prefer fewer, longer functions with comments than digging through dozens of tiny functions spread everywhere. Large functions are usually easier to write and to read.
// Set foo to true
foo = true;
Second, you're (I think) arguing that we shouldn't use comments because they might go out of date, which I think is throwing the baby out with the bath water.
> comments only make sense if they explain the -why-, not the -what- or -how-
That is the wrong heuristic. Comments make sense if they provide useful information that isn't self-evident from the code. Often that is the "why", but it can also be the "what" or the "how". Think about something like the fast inverse square root. A comment explaining how it works is very valuable.
Inline comments are a reflection on the authors' abilities to write good comments. They can be kinda useless, actually-bad, or really helpful.
One canonical example of a "good comment" is explaining why a strange or not-the-least-complex approach was taken to implementing a certain solution. The code is like chesterton's fence, and the comment is a post explaining why it's there. That way, future readers can better assess for themselves whether it's worth their time trying to tear down the fence.
You can imagine a world where all the projects that aren't realistically going to spend the effort on high-quality maintained comments makes the correct choice to skip comments unless absolutely necessary. And where projects that are realistically going to put effort into high-quality, maintained comments, do so.
In this world, comment density would correlate highly with code quality per line of code. Profanity might not, I'm not sure. I do think you'd still find profanity in high-effort, high-quality, maintained comments, but it might indicate lower quality surrounding code, not higher.
And it would still be unclear whether the existence of comments are a cause of higher quality code, or just a proxy for amount of effort and care taken per line of code.
The result is that I don't read any code at all. The whole thing is compiled to the native format that is human language. The code is great for illustration.
If I keep it in separate files as documentation it takes to much effort to find and update. It takes needles extra effort and is less precise.
It is just a personal preference of course but if one had any experience writing code in any language it should be easy to grasp say at 4 am while drunk.
Too many comments might actually be a bad thing. It's more lines to maintain, and sometimes the comments just tell what the code is doing where there is no need to.
When I worked at SAP where VCS for ABAP is ancient and has no analogue for git blame we had a practice of putting a SAP Note next to every code change, since some of the things that we had to implement are dictated by business/legislation, so you need a proper explanation from time to time. Without it, the code becomes unmaintainable.
Sidecars generally suck because they get lost.
Just use comments.
You're not supposed to change commit messages.
The correct lines to blame are the ones right there, not exactly rocket science
A comment goes right there. No tools needed. Mutable. Readable. Contextually in place. And you can even add comments while coding without waiting for the commit.
Is typing // really so much effort?