The Flogging Molly album is done and suddenly the apartment is silent. The fridge is humming. Yellow lights from paper lamps. I’m alone.
Twice now a co-worker commented on my predilection to write a short comment for every method, even if it sometimes doesn’t add much to the function name itself. They no longer comment code – they pick better names. They do this, having read Clean Code.
How strange. I come from the Emacs Lisp world, where we sometimes use long function names and variable names, if they are accessible globally. We use shorter names for local variables. We add doc strings to our functions and variables because that’s what you do. We’re not rigorous about it, we don’t follow a convention of naming preconditions or postconditions, but we pretty much try to name all the arguments and at least write a sentence saying what the code does.
I’ve asked about this Clean Code book on Mastodon. I got a lot of warnings about it.
@brennen offered two links. I liked this essay because it provides examples and quotes that contradict them, showing how problematic the advice can be.
‘Clean Code’ mixes together a disarming combination of strong, timeless advice and advice which is highly questionable or dated or both. – It's probably time to stop recommending Clean Code, by qntm
It's probably time to stop recommending Clean Code, by qntm
The second link reiterates the argument to drop short comments that simply rephrase what the code does, urging programmers to use better names instead. In this case, I don’t think I agree with the premises (either the code is too tricky to document adequately, or the presence of comments will prevent future programmers from making changes).
In programming, I’ve come to see the urge to comment as a sign of danger. – Caveat commentor, by Aristotle Pagaltzis
Caveat commentor, by Aristotle Pagaltzis
As an aside, I think posting about occasional programming topics shows how Mastodon is still full of programmers. So many replies!
#Programming
(Please contact me if you want to remove your comment.)
⁂
I do the same thing. I once tried to jump on the “self-documenting code” bandwagon, and while that’s a worthy goal, comments always help me scan the code more quickly. That’s more important than it sounds. Just keep them up to date!
– ariane 2021-10-06 00:25 UTC
---
I think you should use a mix of self-documenting code and clear comments. In general, code itself should be self-edvident as to /how/ it works, while your comments should explain why. If you have to explain how in comments then for most things you should remove the comments and refactor the code.
In general I think Ada has great guidelines. The design and ecosystem of Ada focuses heavily on making code readable to people that have never been exposed to it (even at the expense of the initial writing), since code is read more than written. The Ada book explains roughly what I follow when programming in terms of commenting and naming.
– nytpu 2021-10-06 04:32 UTC
---
You can over-document internals, just like you can over-test. The result is either breaking changes and lots of work, or a code freeze. On the Fediverse, some people said that others don’t ever read the code comments, and some people said that tests are a more useful way to communicate intent. In my experience, this really depends on the code base. When I write code in Emacs, for example, I almost always only read the doc strings. I don’t read the code, and I definitely don’t read the tests since there often aren’t any. I have high expectations regarding the documentation. Basically, with syntax highlighting such that comments stand out visually, and with editor editor support that shows you doc strings, maybe involving shelling out to tools such as perldoc or man pages, it all comes together naturally: such comments are useful even if they just reiterate what the code does, as they are shorter, and in a natural language, and therefore easier to read, or very complete, with usages examples.
My inclination is the same when looking at Java code. The IDE provides doc strings for all the library functions, except that my co-workers usually don’t document their code so that I am forced to read their code before I can use their functions. A typical project of ours will contain millions of lines of code: all the external libraries, the Eclipse Scout base layer, our CRM standard layer on top of that, and the customer-specific changes and interfaces and extensions where I actually edit the code. The top three layers are under-documented and force me to sometimes delve into it, to read it because it has no javadoc.
Since tests are in separate classes, in separate files, in separate modules, reading tests to understand the code is such a huge time sink, I never ever do it. I just write the tests I need to write in order to loosely test the system, and I rely on them breaking when make mistakes when refactoring code, and I’m always unhappy when over-testing forces me to spend twice the time for every change because many changes don’t introduce bugs that are uncovered by tests but rather tests don’t run until the time is spent to fix them. They simply make everything a bit more rigid. A little extra rigidity is good, a lot of extra rigidity is paralysing.
– Alex 2021-10-06 13:59 UTC
---
I remember back in 1986 that “Compute!” magazine (anyone remember that?) talked about how some comments were not helpful, and that comments for the sake of comments could be clutter. As a joke, I wrote a post-processor that scanned BASIC code and added comments; so “for i=1 to 10” would have an added comment like “lREM: loop ten times”, and “next i” would have “end loop”. Ah, for the days of being a bratty teenager again! 🙂
– 2021-10-07 16:04 UTC
---
On the Internet, nobody knows you aren’t a bratty teenager...
Back on topic, though. The Ada style guide has things such as these:
Make the code as clear as possible to reduce the need for comments.
I disagree with this position because it makes sense if you’re asking somebody who is tasked with reading the file containing the source code. Since you’re already reading the code, trying to figure out whether it contains any bugs, for example, the trivial comments are a distraction. But if you’re using the code, like a library, then things are different. I don’t want to look at twenty lines of code when I can read a two line comment saying the same thing. I don’t want to visit the file containing those twenty lines of code if a tool can simply show me the two line comment I need to read.
Some people might say that I’m talking about an API and they’re talking about most code, which is private methods and local variables. Well, I’m claiming that in my experience, there is hardly any difference. On the contrary, I’m always extending code my co-workers wrote at the office, for example, and I am always angry when they mark their methods as private. We have over three hundred coders doing a gazillion projects, with layers upon layers of code, and it’s pretty unlikely that they can correctly guess which methods are part of the API and which methods are internal functions from my point of view. All they can do is decide this from their point of view and impose this on me, which is exactly that: an imposition. So no, I believe the separation into internal code and API is a false dichotomy. A useful convention, hopefully a documented one, but not a useful separation to enforce by the language, and not a separation to support by using different commenting conventions.
– Alex 2021-10-08 10:08 UTC
---
@amolith listened to a podcast episode where a programmer with sight impairment said that a comment telling them what is happening saves them time. Amolith summarized it as follows:
Those of us without any vision impairment can skim through and understand a whole page of code in just a few minutes while it might take half an hour with a screen reader.
The podcast episode:
In this episode Dominic speaks with Jon about his experience transitioning to using a screen reader and learning to code without his vision. They discuss how some of the tooling works, things other developers can do to make their code more accessible for blind teammates, and more. – Go Time #209
Adding comments for skimming and lookup so that I do not have to actually read the code is something I find very important; Emacs and doc-strings in Java taught me that. And yet the mindset at the office is to only document what reading the code doesn’t tell you, which means I have to read a gazillion tiny functions without ever finding a reasonable comment. It’s all in the function names and variable names, they say. And so huge names proliferate, slowing me down even further. Unhappy!
My reaction to the nearly blind programmer’s experience makes me think of curb cuts.
So it said the curb ramps not only helped people in wheelchairs, and people who used crutches, but women – and it did say women – pushing strollers. And delivery men with their deliveries, and bicyclists. And then it kind of ended with something like, it was creating freedom of movement for everybody. – Curb Cuts transcript, an episode of 99% Invisible
Curb Cuts transcript, an episode of 99% Invisible
Looking back, I think ariane’s comment up above was the most succinct. 😀
… comments always help me scan the code more quickly. That’s more important than it sounds.
Yes!
– Alex 2021-12-25 22:55 UTC
---
When I start with the code, I use my documentation writing as the time to synthesize what I wrote. To explain and instruct my future self (as well as other folks engaging with this portion of the code base). – The Why and How of Yardoc
– Alex 2022-03-17 18:41 UTC
I like long functions that do a long and complicated thing. They take a thing and check it, transform it, save it, compute it, and on and on and then they return. Yes, if you want to test all the special cases, you need to write multiple tests. But consider the alternative: many small functions calling each other. Sure, testing each one of them is easy, but now you need to remember how they call each other, in what order, and whether they're still needed, and whether somebody else is using this little function now and so you can no longer change it. Ah, of course you could put it in a module and hide the internals from everybody else, and then you still have to write a few top level tests and the code as a hole is complicated and yes, I can get back my inner peace by just looking at those small functions that I understand. But as soon as my mind wanders to all the other functions, I'm confused again.
@kevin@dice.camp says that at work he's "maintaining legacy code with methods that are hundreds to ~1,000 lines long. Not a fan." I can understand that!
I guess I'm too young for functions hundreds of lines long. I already start to get that nagging feeling after 120 lines and now that I think about it it is probably because some of my co-workers seem to feel that more than 4 lines is already stretching it and they love 50 character long names for functions and variables because they read Clean Code at an impressionable age. See above!