Bug#727708: systemd code documentation

2013-12-03 Thread Tollef Fog Heen
]] Russ Allbery 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? Did you see the

Bug#727708: systemd code documentation

2013-12-03 Thread Russ Allbery
Tollef Fog Heen tfh...@err.no writes: Did you see the «Documentation for Developers» section on http://www.freedesktop.org/wiki/Software/systemd/ ? It's more of an overview/design doc than function documentation, but it might be some of what you're looking for. I've also forwarded your

Bug#727708: systemd code documentation

2013-12-03 Thread Eugene Zhukov
Russ Allbery r...@debian.org writes: This documentation is really, really nice, but it's a bit different than what I was talking about. I should be clear, though (and please also do mention this to Lennart): the user-facing and the integration documentation for systemd seems quite good. This

Bug#727708: systemd code documentation

2013-12-03 Thread Ian Jackson
Eugene Zhukov writes (Bug#727708: systemd code documentation): The frequency of comments sometimes reflects poor quality of code. When you feel compelled to add a comment, consider rewriting the code to make it clearer. Please can we avoid arguing about this particular bikeshed here. Thanks

Bug#727708: systemd code documentation

2013-12-03 Thread Russ Allbery
Eugene Zhukov jevgeni...@gmail.com writes: The frequency of comments sometimes reflects poor quality of code. When you feel compelled to add a comment, consider rewriting the code to make it clearer. That would indeed be a succinct statement of the other perspective on code comments, which

Bug#727708: systemd code documentation

2013-12-02 Thread Russ Allbery
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