I like to think I have a very strong trust in all the members of the team I work with to tell me things I need to know to get my job done. My team members may not always be there right next to me, feeding me tidbits of information, so I trust them to leave what they were thinking in the code they leave behind. Sometimes it is harder to read some people’s thoughts, but most of the time, I get what they are saying. It’s always a great day when someone has the courage to put that comment down that saves you hours of trying to work out why something works the way it does without delving into its great recesses. Thanks for the comment and the hours you saved me today in my bug fix.

I don’t know about you, but if I see a three-dimensional array being returned by a method in Java, alarm bells start going off (without, of course, suitable (and it better be mighty) justification). I have no idea how this method was added to the code base without review by another developer (my guess is that it wasn’t), but proper developer hygiene and good conscience (who would want to inflict it upon anyone else?) won’t let me leave it there. After studying the single method for over half-an-hour and dragging over the original author, I finally realised what it’s purpose in life was.

There are already far too many articles about what simplicity is (try this link), but my favourite rule of thumb is, if you have to stop and think about what code is doing while you’re reading it, it may be excessively complex. I avoid writing complex code, not because I am lazy or stupid, but because it is a waste of time that prevents me from writing other code that adds greater business value.

A RAM test doesn’t stop reporting numbers like this. The computer I develop on at work started freezing after numerous JVM shared object crashes. Testing the RAM in another machine and other RAM in my machine seemed to indicate that a) the RAM had not been properly installed in the first place, b) had magically come loose over the weekend, or c) is dodgy RAM (I’m voting for the latter). This is the first day that I have been unable to develop any code, it made for a very good opportunity to do other things.

I’ve always been frusted by the (lack of) information contained in Ant’s so called ‘Manual‘. Considering it has been around for so long, I have found it lacks the wisdom of best practices or tips for writing more maintainable scripts. I probably should have bought copies of Ant: The Definitive Guide and Java Development With Ant but I have never really needed it (and I was sure its contents must already exist on the web). Little did I realise that this page existed with more than enough of the sorts of information I wanted. Oh, and their wiki is well maintained too.

Nat Pryce writes a good article about self-documenting code not necessarily being completely bare of comments, of which I am in total agreement of. Like many practices, developers tend to abuse the self-documenting code practice, suggesting that code should be stripped of all comments. Excessive amounts of comments are probably a good indicator of poorly written code, but some advocates forget that the premise of this practice is to get rid of as many redundant comments as possible, not necessarily all of them.

Applying the renaming suite of refactorings such as “Rename Method” can be used to get rid of ridiculous comments that describe what they do, like “This method returns a sum of numbers.” This can also be applied to all other items like classes, fields, constants, aspects and attributes.

This post started off as a comment for Nat’s entry, but I thought it would be useful to give more examples on why you might add comments.

Choices of Algorithms
Implementing some functionality normally requires some sort of trade off and these trade offs are sometimes important to document. Factors such as a framework, deployment or performance constraints might require some code to be written in a certain way, normally resulting in obfuscation. Communicating to other developers why this obfuscation exists can help because if that constraint goes away, then the code could be refactored without consequence.

Capturing Richer Domain Knowledge
Domain objects tend to be used at the core of a system, and I find, are usually the least documented. Well named attribute and class names can fundamentally describe what they represent, but may contain information or context for people new to the domain. For example, it took me a while on my current project to work out that the two terms our business analysts used actually referred to the same domain object. One was used when referring to it outside of the company context, the other used when dealing with it from inside. Especially when you are stuck with a domain model that cannot be changed it can be important to document things like differences between one attribute and another and the constraints some attributes may have.

Referencing User Requirements
Sometimes developers have to code a few things that don’t necessarily make a lot of sense on its own. Special cases mandated by users and captured by business analysts just must be completed. Fixes to bugs caused by incorrectly written user stories or overly complex domain models are another circumstance that may introduce code that, on its own, may not make a lot of sense. I find it has been useful, having done much maintenance programming lately, to add a reference to the issue that a block of code was added for. In the overly complex part of the system (caused because of the overly complex domain model that cannot be changed at the moment), the references to the Jira issues help to provide more context to the code that was added and why they are necessary.

Like all aspects of writing software, comments still requirement good judgement of how much business value they add. If you think it’s going to help someone else understand it, use it, or maintain it, perhaps its worth documenting. On the flip side, if you find existing documentation to be wrong, misleading or just a plain duplicate, then do the correct thing and remove it or fix it so it will not cause any further harm. On a final note, well written test cases can also be used to remove some classes of comments (those that describe business requirements or required functionality).

Thought I might create a new feed to better separate my technical (generally work-related) rants and then my every other day blog entries. The standard feed (wp-rss2.php), that this post should be a part of, will from here on contain only the technical ones. The feed containing all other categories is now available on (wp-rss2all.php). I’ve been posting a few too little geeky posts lately, so I thought it best to have a separate feed since I know one particular site uses the original feed.