Developer Aspirations

YAPB - Yet Another Programming Blog



February 2011

Succinct Code

by Colin Miller, on development, elegance, Object Oriented Programming, Reusable Code

This has been talked about in quite a few places and in a variety of ways. Most recently I was reading an article on PragPub about abstraction that caused me to pause and think about how I write methods. I've always had a set of best practices, but I think I can add another to it based on some information in that article.

[caption id="attachment_387" align="aligncenter" width="518" caption="Sometimes I imagine my cat is judging every line of code I add, every variable I name, and every parameter I have in a method. Not really, but you could imagine that based on this picture couldn't you?"]Mischief is watching[/caption]

Those practices have already included things like keeping my methods short. Some say that if your function or method needs to be scrolled to see the whole thing than it's too long (and you have to have your screen set to 80 char cols and 25 lines long for it to count). I try to keep my methods under 10 lines if possible. The shorter your methods, the easier each is to understand.

Any non-trivial (ie, not a getter or setter) method has useful JavaDocs. I already went over commenting in the last post, I don't think I need to reiterate.

Classes shouldn't have hundreds of methods and be thousands of lines long. If this is the case, perhaps that class is really doing the job of several other classes. Classes and variables should also have succinct but fully understandable names. Any variable or class name that has some ambiguity on what it does should have a small comment near where it's created to better explain. Also as a general rule, the smaller the scope, the shorter the name can be. Using 'i' in a local for loop is ok, using 'i' as the name of a property representing an overall index of a class is less ok. Using 'i' as the name of a parameter in an interface with no JavaDoc is just not helpful.

The most recent best practice from that article is to limit parameter list length by combining parameters into a containing object. If you have several methods that each take the same list of 6 arguments, why not combine those arguments into a single object and have each method just process that object? This also allows you to expand what parameters a method can accept without changing the method signature (and therefor breaking compatibility with other code that relies on it) by just adding new fields to that containing class.

This is especially important in methods where you find that the parameter list is constantly changing during development. If that method is used by many other classes, you have to perform a refactoring to make all of those method signatures valid. If instead you use a single containing class and just add new fields to that class, the function signature won't change and, assuming those new fields are optional, code using that function don't need to worry about your new parameters. You can always throw an exception if the required parts of that object are missing, and since you're unit testing everything you'll catch those right away.

comments powered by Disqus