--- Begin Message ---
- To: Tollef Fog Heen <tfheen@err.no>
- Subject: Re: [Russ Allbery] systemd code documentation
- From: Lennart Poettering <lennart@poettering.net>
- Date: Fri, 6 Dec 2013 15:35:21 +0100
- Message-id: <20131206143520.GB28796@tango.0pointer.de>
- In-reply-to: <87pppbxafk.fsf@xoog.err.no>
- References: <87pppbxafk.fsf@xoog.err.no>
On Thu, 05.12.13 22:19, Tollef Fog Heen (tfheen@err.no) wrote:
>
> Hiya,
>
> I poked you on IRC about this, but I suspect it disappeared in the
> noise. Any chance you could point Russ at any other resources that he
> should use? You can read the entire bug log at
> http://bugs.debian.org/727708 ; Russ's message is
> http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=727708#803 .
>
> (Feel free to respond to the bug at 727708@bugs.debian.org too, of
> course.)
Our general approach there is that comments shouldn't drown code. Hence:
comments for everything that cannot be obviously read from the sources,
but not comments for everything we ever write. For example, if you have
a function that is called let's say "unit_load()" then this is already
indicative enough of what the thing does (loads a unit), that we
explicitly do not put a comment there.
Note that our public APIs are documented in man pages, and those are not
placed in the code. You could probably make our statistics look better
in the eyes of the the-more-comments-the-better fraction if we'd not
build those man pages from docbook but rather from inline source code
comments. (I'd even be willing to do that, but I know of no tool that
would allow embedding docbook man XML in C files)
Anyway, no doubt Upstart has more comments. And no doubt we probably
could add mor to our sources. But ultimately this doesn't affect our
contributor base too much as it turns out, since we have so many more
contributors to our code than Upstart got... ;-)
Also, I am pretty sure that Knuth' commenting style is rather extreme
(and didn't drown one of Debian's own projects, ifupdown so that nobody
wanted to hack on it anymore?) I am pretty sure Knuth commenting makes
sense for writing books and for inner core algorithms, but our code is
not like that. The identifiers we use should mostly be sufficient to
indicate things.
Ultimately it's a matter of taste I figure...
Lennart
--
Lennart Poettering, Red Hat
--- End Message ---