Re:Libui: a portable GUI library for C
by eps on Sunday May 20, 2018 @04:53AM
(#17111888)
From my experience there’s little to no correlation at all.
One of the most beautiful C codebases I’ve seen - the SSH IPsec stack - had the most succinct yet comprehensive documentation. Linux kernel has virtually none of the latter but the quality is still very high. Then there’s something like Miranda IM - complete clusterfuck of the code, but really well documented. A lot Java code is that way too, but also with documentation rehashing trivial facts rather than explaining anything.
However, what does seem like a sign of a good code is longer intro comments in header files that explain the design rationale and how things fit together in general. It’s basically a level up from verbose API description, but when done right it makes the API obvious without any further detailing.
One of the most beautiful C codebases I’ve seen - the SSH IPsec stack - had the most succinct yet comprehensive documentation. Linux kernel has virtually none of the latter but the quality is still very high. Then there’s something like Miranda IM - complete clusterfuck of the code, but really well documented. A lot Java code is that way too, but also with documentation rehashing trivial facts rather than explaining anything.
However, what does seem like a sign of a good code is longer intro comments in header files that explain the design rationale and how things fit together in general. It’s basically a level up from verbose API description, but when done right it makes the API obvious without any further detailing.