Well not the ones you may think about. It’s been years since I manipulated an actual pointer in my code.

I am still reflecting on that graphic design book I was talking about here where another important thought was that one of the goals of graphic design is to lead the reader efficiently through the document.

And I have been wondering since then if and how I could apply this to my software. After all, it is meant to be read, if only by a maintainer. So how do I make sure that a maintainer immediately captures the ideas and the intent that I coded ? How do I let a new developer understand what I intended to do and why I designed it in a deliberate way ? Or the way I left a complete mess  sometimes.

Well it really starts with software development 101: sensible names for classes, methods, variables, members, functions and what not. Don’t let your reader guess what this thing is doing. It also about the single point of return and the verification of parameters at the beginning of method. A mix of conventions, explicit names and familiar patterns (yes design patterns) that reduces the noise. It is also about concision and simplicity: short text, do a single thing at a time. Keep things simple (you know all those static code metrics that PMD calculates for you ? keep an eye on them).

But all that does not provide any insight on the structure of the software. So you have to reach for higher ground. First through the source code layout. The choice of modules, the dependencies described in your build system (do I think Maven ?) give valuable insight design of your software.

Final piece in the puzzle: the tests. Specifically, for this purpose integration and functional tests as they provide examples of how the sub systems are assembled and work together. Once again, naming is crucial. If you use an ?unit framework, don’t be shy of long long long names that fully describe what is tested (remember, you will never have to type these names again). Or even better, use BDD tools, like rspec. An important point on the tests: they should be written as elegantly and as well as the so-called production code to be useful for that purpose.

Okay you think, that’s nice and good but what about documentation ? Documentation ? What is that I say ? Well seriously, documentation is great for end users of tools, not as good for the people who will actually change the code. On the other hand it is sometimes very useful to highlight a particularly difficult point. To document extension points, nothing beats a short example. Also a complete and well maintained documentation is absolutely mandatory for the configuration files. Especially if they are written in XML because it is almost impossible to make an xml document easy and nice to read !

So here you have it, my ideas to make it easier for people to get an understanding of your software. I strongly suspect that it would be possible to research code patterns that make it even easier to get into someone else’s code. But overall, my feeling is, if you think about it while coding, and leave plenty of white spaces, the world will be a better place.

Next post: Polish on my software.

This entry was posted on Monday, October 22nd, 2007 at 10:56 pm and is filed under Design. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.