Re:Ask HN: What are the “best” codebases that you've encount...
by dwild on Tuesday July 30, 2019 @10:17AM
(#20565011)
That comment is exactly what I mean by when needed.
That does confirm that they are making pretty amazing code. I would have much prefered to get that file instead of the other one :P.
They do have a redundant comment at someplace but it's clearly a tiny minority and they aren't losing any one time.
I'm thinking more of examples like this: https://github.com/postgres/postgres/blob/master/src/backend...
I just picked this at random from the storage subsystem, but I think it highlights what I mean. The comments are mostly about context. The comment for the routine is about when and who calls it, so that someone that reads the routine has that in mind. The specific line I'm linking to highlights in English prose that the correctness checking on the page headers is just a minimum guard and should not be fully trusted.
Back in the day I would have argued "oh, well, but you could break that into a function called "provisional_page_header_check(..)", or something. But.. there is nothing in the compiler that checks that function names stay in sync with their implementation any more than there is for comments. Writing it as a comment lets you use regular English sentences, breaking out a function takes that away and adds no compiler protection.
It's also.. friendly, somehow, to me. Working in this codebase is like participating in an ongoing and very slow conversation, which feels very pleasant.