Read this article on Less Software Engineering. He says what I was trying to in my article much better in places. The article is focused mainly on C++ development, but there are a lot of gems included in there. Of course, there were some things that I disagreed, but they were minor squabbles. Here's some excerpts:
- "1. Use creativity to simplify, not to show off.
2. Avoid complexity. Design then code.
3. Be extremist. Maximize simplicity.
Systems always turn out to be more complex than you expect. Guard against this by pushing for the simplest possible design."
- "Every programmer should strive to write code whose behavior is immediately obvious to the reader. If you find yourself writing code that would require someone reading through it to thumb through a manual in order to understand it, you are almost certainly being way too subtle. There is probably a much simpler and more obvious way to accomplish the same end. Maybe the code will be a little longer that way, but in the real world, it's whether the code works and how simple it is for someone to modify that matters a whole lot more than how many characters you had to type."
I don't like abbreviations and this is why. Without abbreviations, readers of my code know my intentions and they are obvious.
- "One of the primary tools for producing maintainable code is minimization of scope. All variables should have scopes consistent with their lifetime and intended use.
There should be almost no global functions or constants."
I would say NO GLOBALS, but I generally need at least one. But, I fight it like hell!
- "Use classes or typedefs instead of raw types like int. If you are using an int (or some other primitive type) to represent some concept, such as dollars, hide the representation via a class or typedef"
AMEN! This isn't a problem in Smalltalk, but is in C++ and Java.
- "Choosing names is one of the most important aspects of programming"
- On Comments:
"Don't just repeat what's in the code. The biggest mistake made in documentation is simply to repeat what's already obvious from the code, such as the trivial (but exasperatingly common) example:
// // Increment i. // i ++;
Documentation should provide higher-level information about the overall function of the code -- what a complex collection of statements really means."
OH YEAH! But, I would say your code should be easy enough to read. But, when it's not a little comment can go a long way. I generally need to do this when dealing with third party libraries in Java.