10 commandments for creating good code(makinggoodsoftware.com)
makinggoodsoftware.com
10 commandments for creating good code
http://makinggoodsoftware.com/2009/06/04/10-commandments-for-creating-good-code/
7 comments
More important then writing short methods is consideration of the methods purpose and name.
Any method should have only one purpose and that purpose should be expressed in its name. If it can't be expressed that way the function is to complex.
Any method should have only one purpose and that purpose should be expressed in its name. If it can't be expressed that way the function is to complex.
True -- And some code I've read (such as Rails) uses an options hash that gets augmented and passed all over the place. This, I think, diminishes readability and could (in the wrong hands) endanger reliability.
#8 and #9 contradict each other.
If you're supposed to create an "interface", let's assume that's the public api.
But if you're trying to make methods small enough that comments are not needed, you're doing so for implementation purposes, since chances are most of those methods will be private.
Personally, I think a few comments are nice, especially to help orient someone their first time reading the code.
If you're doing something so magical that it requires comments to have any hope of being understood, you should have a really good reason for using so much magic.
If you're supposed to create an "interface", let's assume that's the public api.
But if you're trying to make methods small enough that comments are not needed, you're doing so for implementation purposes, since chances are most of those methods will be private.
Personally, I think a few comments are nice, especially to help orient someone their first time reading the code.
If you're doing something so magical that it requires comments to have any hope of being understood, you should have a really good reason for using so much magic.
Nice little article until the wheels fell off: "Comments are evil". Couldn't disagree more. Few things suck worse than having to dive into someone else's code that isn't commented.
Please read this other post for details in what I mean when I say that "comments are evil" http://makinggoodsoftware.com/2009/06/06/comments-are-evil/
In a lot of the cases the code should be the comment. Have a comment at the top of the function specifying what inputs are valid, what it returns, does it alter the data passed in, what the function actually does, etc....
Although this is OO dogma, it's contradicted by the research literature. Empirical studies of function length show no benefit to shorter functions. Several studies have found them to be correlated with higher defect rates and costs (up to a threshold of a few hundred lines, at which point defects and costs start to rise again).
I was suprised when I first heard this. I think it's explained by the fact that adding function calls is not logically free: it adds conceptual overhead. Factoring code into shorter functions for its own sake doesn't produce benefit that exceeds this cost. There's a fundamental tradeoff here, which a dogmatic belief in short (or long) functions just misses.
Of course, the higher-level the language the shorter all your functions become.