Bug#727708: systemd code documentation
I should say up-front that I don't consider this to be a decisive issue,
but since it was raised and I did a bit of investigation, I wanted to
report my initial conclusions and see if I missed anything or got anything
wrong.
I did a quick code inspection of the code base for both upstart and
systemd. This was quite far from any sort of audit, and was necessarily
quite limited. The goal was to get a quick feel for the code "smell" and
style, and to see how comfortable I would be working on the source base.
First, I'll say that both projects seem like generally well-written C.
They both use well-defined small functions, there isn't a lot of
deeply-nested structure, they both have published coding styles and
clearly adhere to them, and in general both packages strike me as written
by people who knew what they were doing and have been kept up to date.
(By comparison, sysvinit looks like old and somewhat crufty UNIX code and
makes me nervous and uncomfortable, even though it's much simpler.)
That said, on first impression the upstart code struck me as significantly
superior to the systemd code in terms of orientation for a new developer
or someone attempting to isolate bugs, primarily due to substantial
differences in internal documentation. In systemd, each function seems
well-designed and isolated and does document some of its assumptions with
asserts, which is good style, but there are almost no comments. Functions
usually don't have leading comments describing when to call them, header
files don't comment functions, files don't have leading comments to orient
the reader towards the purpose of the file, and most of the internal
comments were cryptic to a first-time reader and struck me more as
marginalia than commentary.
By comparison, upstart was lovely code to read. It uses Doxygen, which I
can take or leave, but more importantly it documents the internal
interfaces and functions and provides much more internal orientation
(although it could still use leading commentary for each file).
My question here is: am I missing something in systemd? Did I just look
at the wrong files, or not look deeply enough, or is there orientation
documentation somewhere else where I didn't see it? Is there something
about this comparison that's unfair?
I'll admit that this is a debated point of style, and some programmers
think that regular commentary make the code less readable and tend to
become out-of-date. I'm in the other camp; I prefer orientation
commentary on each logical block of code, and probably write code that
some people would consider excessively commented. I think code should
tell a story to someone who is reading it and invite understanding. (I've
probably read too much Knuth, although I don't think Knuth's method of
doing this worked.)
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: