Coding Standards and Minimal Design
Today I saw a chunk of code that was checked in and had a very hard time understanding exactly what it was doing. The comments didn't really help, and the variable names weren't a lot of help either. I actually had to walk through the code a line at a time to understand what it was doing. Now I'm no paragon of design and coding virtue, but there's a point where you really need to hold yourself - and the folks you work with, to some bare minimum standards in this area. A 20-line method in Java should not take someone to walk through the code to understand what it's doing. I read Kernighan's quote: Debugging is twice as hard as writing the program, so if you write the program as cleverly as you can, by definition, you won't be clever enough to debug it. and agree with it 100%. The extension of that might be: If you have trouble understanding what you just wrote, the other guy, six months from now, will have to re-write it.
So I figured out the code and started cleaning it up. It didn't need the functionality changed, that was fine. It was the variable names and the flow, and more than anything, the lack of comments saying what was going on and why. I know these are things that aren't popular with a lot of developers, but they make the job of maintenance and extension a lot easier. It also won't hurt to spend just 15 or 20 minutes looking at what you need and trying to see if there's a better way than your first cut. Don't spend the entire day, but spend a little bit of time to make sure that you're putting down something that the next guy will be able to pick up easily.