Any half-decent coder will agree that writing readable code is important and that good comments are a part of that.  More and more I’m getting the impression that that’s not enough.

Code should be a thing of beauty.  Not necessarily "oh that’s a beautiful algorithm" and definitely not "oh wow that’s clever" but beautifully laid out with every blank line considered for meaning and well thought out comments everywhere.  Every construct and every line should match the selected coding style and real thought should be put into why that particular coding style was selected.

All that sounds like a waste of time and productivity – you don’t need to go that far for the code to be maintainable and in fact I suspect that in the simple case writing beautiful code does cost productivity even in the long run.  The reason I think you should do it anyway is the classic slippery slope argument.  If you let the odd thing slip because they don’t really matter then you are more and more tempted to let something else slip.  You don’t feel bad if that method isn’t commented because there are already a couple of other methods in that file without comments.  You don’t care if that line you just wrote isn’t as clear as possible because the rest of the method is a little complex anyway.

More importantly though, you lose the ability for tools like Checkstyle to really benefit you.  If you have thousands of checkstyle errors and warnings throughout the codebase it’s difficult to notice that the code you just added creates a new one.  If the codebase is nice and clean though, being the person who creates the only checkstyle error isn’t much fun so you tend to avoid doing it.  Classic broken window stuff – as soon as one window is broken the rest of the windows rapidly get broken.

The other big advantage of writing beautiful code is that it demonstrates good coding practices to anyone who reads that code and anyone who reads beautiful code immediately has a high level of respect for the programmer and for the codebase.  They’re more likely to take time to understand problems and contribute fixes if they respect the codebase rather than seeing a mass of uncommented code, swearing at the programmers and going off to find a better written tool.

The best advice I can give then is to install the checkstyle plugin for whatever IDE you use (or something equivalent), tweak the configuration to suit your tastes (but don’t disable rules without carefully justifying why that rule provides no benefit) and then make sure that as you code you avoid even the smallest of warnings.  Your code will thank you for it and those who read your code will be worshipping at your feet in no time.