On Mon, Jul 21, 2025 at 07:26:07AM +1000, Warren Toomey via COFF wrote: Well, in a long lived code base, comments can rot. I'd much rather have to read the code and figure it out than have a comment that is no longer true send me down a wild goose chase (it's happened more than I care to think about). I tend to comment structures quite a bit, globals and locals, have a block comment above the function saying what it is and it gets sparse from there. There may be inline comments but they need to do something a lot more useful than i++; // increment i <-- this sort of comment is worse than useless I also have a style that is int *p = 0; char *foo = 0; int ret = 0; // lots of code err: ret = -1; out: if (p) free(p); if (foo) free(foo); return (ret); } Most of the BitKeeper code follows that style, no unitialized pointers, we did use a lot of unless (p = malloc(whatever)) goto err; style of programming. Memory management in C is primitive so you have to adopt some consistent style to avoid errors just because someone did something different. I always said "optimize for reading, not writing". I've also said "anything that you wrote 6 months ago, you will approach it as if it is someone else's code".

On 7/20/25 5:26 PM, Warren Toomey via COFF wrote: I think the age of my code base stacks up pretty well, and I find myself commenting what I think are the complex parts and changes very heavily. Above all, I want to be able to answer this question from my future self: what the hell were you thinking? I find that I'm not nearly as clever as my younger self. Detailed change log entries are essential as well. Chet -- ``The lyf so short, the craft so long to lerne.'' - Chaucer ``Ars longa, vita brevis'' - Hippocrates Chet Ramey, UTech, CWRU chet(a)case.edu http://tiswww.cwru.edu/~chet/

On Sun, Jul 20, 2025 at 5:26 PM Warren Toomey via COFF &lt;coff(a)tuhs.org&gt; wrote: My major gripes about comments are that people tend to write them poorly, and they aren't generally checked by the compiler/interpreter: a poor, out of date, comment can be worse than no comments. But comments also have issues around discoverability and locality; I have found that they are not good as a means for system-level documentation, serving best to explain rationale at some very local level of code. Crucially, those comments are only really useful when I already know where to look for them, and while they may explain a particular quirk of some code, they often don't help me understand the system/interface/tool as a whole. However, the "not checked by the compiler" thing has some exceptions these days. Some languages have the notion of "documentation tests", in which one can write unit tests in a comment, flanked by special syntax so that they are checked by the compiler and are executed as tests when invoked a certain way; this is useful for keeping code examples up to date as interfaces change. Rust is a good example here: https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.h… An issue is that people try to go beyond this and use comments for more general documentary purposes, for which they are not well suited; at least not without significant additional tooling. Google mandated that C++ header files all contain comments that described classes _and how to use them_ at length; this was useful, but sometimes really do want an external document of some kind that describes things at a higher level. But comments are just one way of introducing documentation into a system, even at the source code level. Python and many dialects of Lisp both have a notion of "docstrings", for example, that are accessible from the REPL, and serve an overlapping purpose, but are semantically different objects than comments at the language level. "Doc comments", used for automatically generating system-level documentation, are increasingly common, whether part of the language or its canonical toolchain itself, or retrofitted with external tooling. Ah, this old saw. :-) For me personally, I try to minimize my _need_ for comments, to whatever extent that I can. This may take the form of introducing a named, but perhaps otherwise unnecessary, intermediate variable to hold some part of a computation, where the alternative is to make the computation itself part of a larger expression that would then be less obvious. Similarly, I may introduce a function returning a boolean to encapsulate some predicate behind a descriptive name. If a well-aimed type can make a comment superfluous, say by encapsulating some invariant of the data, and the language supports it, then by all means introduce a new type. If this sort of technique can make a comment entirely redundant with the code, then I favor removing the comment. On a related note, John Ousterhout recently had a long-running online "debate" with Robert Martin, the agile influencer. They recorded the results of this in a text file that was then uploaded to Github; I heard about it when John wrote to the mailing list for his book, "A Philosophy of Software Design". The subject of comments featured heavily in this discussion, as Martin is infamously averse to them and Ousterhout views them as essential. You may find it interesting: https://github.com/johnousterhout/aposd-vs-clean-code I'm not sure why Ousterhout, who has a long track record of building real systems, chose to give Martin, who does not have a track record of building real systems and further displays all the trappings of a charlatan, a platform for these topics, but he did. Sadly, when Ousterhout mentioned it on the mailing list, it failed to generate very much discussion. I had my own response, much of which I cleaned up and consolidated in my own response to their Java prime number generator example, and that I pushed to Github here: https://github.com/dancrossnyc/literateprimes/ - Dan C.