In my experience - yours may be different - there is something you could call the Goldilocks zone for comments. Too many comments can obscure the code, and lead

In my experience - yours may be different - there is something you could call the Goldilocks zone for comments. Too many comments can obscure the code, and lead to those horrible moments where the code and the comments disagree. But using them too sparsely can be a problem, too, especially if you're looking at a 1000 line file with three comments that all go "// ???" (I have used these question mark comments myself as a reminder, "if this change breaks something, I should start looking here", but I was always careful to remove them as soon as possible). The best advice I've been given on comments was somewhere in the coding guidelines for the Linux kernel - if you have to write a comment to explain what your code does, consider rewriting it so it will be obvious; but it's often a good idea to write a comment explaining why your code does something in a particular way. I have, on occasion, seen code that seemed horribly convoluted or inefficient, only to find out the hard way that there was a good reason for it being that way, often having to do with idiosyncrasies or bugs in the OS or external libraries. In those cases, I found it extremely helpful to write a short comment explaining what mess you are trying to work around. Not only will this keep others (or yourself, a year from now) from trying to mess with that code, it will also encourage people to fix it if the reasons you state in your comment no longer apply (maybe the OS/library/compiler has been fixed, maybe you're on a different platform, ...). If, for some reason, I find myself writing a longer-than-recommended function/method, I to insert comments to make the structure of the code clear, so if I find out later that there is a bug in the code that, say, creates the database connection, I can find that code more easily. Of course, factoring that code into several functions/methods and call them from a short top-level one would be better, but just having to read through a couple of screens of code without any sign posts is worse. (Much of the same applies to documentation, of course. I you need to explain what a function/method does, because its name does not tell you, you might want to rename it. But if there are any caveats you should be aware of - e.g. "Don't ever pass a NULL pointer to this function, because it does not check for those and will segfault the program" - the docs should point them out to you.) (I am, of course, writing all this from a more general point of view, I have never looked at the systemd sources, and I'm not sure I want to.)