All in all, I am a peaceful person, really :-) Instead of wishing for slow and painful death to all of those who don't bother with commenting their source code, I'd very much like to see these guys damned in Inferno, eternally forced to maintain other people's uncommented crappy code ;-) That's not so painful, now is it, and I can't imagine a better training of empathy skills (i.e. getting an idea how the other person - in this case the one maintaining your uncommented code - might feel).

Last autumn, some time around openSUSE 10.3 release, I was so burned-out and broken from fixing bugs in the code of someone who must have really learned How-to write unmaintainable code pamphlet by heart, that I've written up short How to write maintainable code manifesto. As I've recently inherited several thousands of lines of very similar code esp. when it comes to readability, together with the amount of comments, it's time to revive the manifesto again. So, here we go:

for ( int i = 0; i < 100; i++ ) 
{
    //Over-stressed female's note: The future maintainer of
    //this code might be not as smart as you are - what is 
    //self-evident and obvious for you, can be completely
    //unclear to him/her  
    //This loop prints what you are supposed to do to stdout.
    //100 times :)

    cout << "I will comment my source code" << endl;
}

Ok, now let's take it seriously:

1. Indentation is not for sissies.

   Take care of indentation (if-else blocks, loops, static structures). When doing it, use common sense, you really don't have to pipe all the source code files through indent utility (which might not support your favourite programming language anyway). It is quite challenging to read and understand, for example, this code snippet
   

   
   
       if (strange_hash["some_key"]:""==something && other_hash["obscure_key"]:nil 
       ==somethingelse) return;
       my_cool_function();
   

   
   Not to mention introducing new bugs to the software just because its author does not care about indentation.

2. Bug IDs are welcome

   If you fix a bug (implement a new feature), write a brief comment to the corresponding part of code ( for example: /* Do not call green_parrot() function here, it has been moved to module pink_elephant.ycp - bug#12345 */). It will save you and your colleagues from detective investigation in the future, when you will have hard time digging deep into version tracking system logs and finding out when this part of the code has been changed and why. Especially when a new bug is introduced by fixing an old one.

3. Talk to me, svn log

   Write clear and concise version tracking system check-in messages. If possible, attach also ID of the bug you are fixing (feature you are implementing). It is then easier to find out what is it the poet ... er, software engineer ;-) wanted to imply by this particular change. You don't have to write novels, but a comment of a type "Fixed editing of purple_seagull items" deserves at least bug ID reference, so the others can understand what exactly it is you have fixed.

4. (enhancement)

   The less bugfixes per one check-in, the better

There we are. I'm anxiously waiting when I will be given "Nuisance of the Year" award :-)