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.

Today I worked on an interesting bug that required us to forcefully push out a new copy of a file to any client that connected to our web application. The file was a javascript file containing several functions which are used by our application, one of which was modified and is now used as a trigger for an important part of the application (don’t ask why). Clients to our application are the general public, so forcefully clearing caches was certainly not an option, but our solution might have been made easier if we were allowed to change the name of the file, or even the name of the function. Unfortunately other existing technical requirements did not permit this.

A quick google-later gave me enough evidence that header tags like <META HTTP-EQUIV="PRAGMA" CONTENT="NO-CACHE"> (for HTTP 1.0), <META HTTP-EQUIV="CACHE-CONTROL" CONTENT="NO-CACHE"> (for HTTP 1.1), and <META HTTP-EQUIV="EXPIRES" CONTENT="0"> would not be enough to trigger a refresh of the client’s versions. Some sites described that writing out values in the HTTP-Headers might also work, but I wanted to avoid it for not being a very simple solution.

In the end, the solution we deemed acceptable was to simply add a query string to the end of the file so that clients would be tricked into thinking that it was a new file, turning something like: <script src="/scriptForRefresh.js" type="text/javascript"/> into: <script src="/scriptForRefresh.js?forceMeTo=refresh" type="text/javascript"/>

I was in a situation this week, where I have been fixing bugs in one particular part of our system for total of two weeks. This situation was created by too many reasons to really list (or perhaps warrants its own separate entry) and is a relatively unusual circumstance for our project since a maximum of two days is all we tend to need for each iteration. Being immersed in ‘maintenance mode’ for so long has really highlighted the different set of skills you tend to draw upon in contrast to our normal operating mode. It has also brought to my attention a few issues that can really help or hinder you when working in this mode. Here’s a few of them:

• Good logging statements (being careful not to damage the readability of code) that detail the complex state of a system in a readable is definitely helpful as you don’t need to add them yourself or to your debugger.
• Fast unit tests help to give early feedback when making changes to the system and a change breaks its contract with other components.
• Fast integration tests gives you the confidence that your system will continue to operate as it has in your production environment.
• Identifying a bug in business requirements before code is written is definitely cheaper than fixing it later on.
• Poor exception handling can mask the original source of error. For example, on a previous project, I remember the overly complex exception handling architecture triggered a NullPointerException when handling a simple business exception.
• Code smells tend to become even more offensive as you wade through its source, which at least helps to identify areas that are good candidates for heavy refactoring or redesign).
• Repeatable test scenarios for a reported bug which are then translated into code are important against protecting against regressions.
• Though I agree with the whole philosophy of self-documenting code, I still find comments are important. I find the best ones tend to explain why a block of code was written in a particular way instead of another or the potential side effects changing that may have.

The term ‘unit test’ was being thrown about today at work but so many things about its context were just plain wrong. Just because our testing framework is called xUnit and each method happens to be called testX doesn�t make it a unit test. People have spent (far too much) time attempting to classify all types of tests coming up with categories like functional, acceptance, integration, or unit-integration tests. In my humble opinion, I tend to think of all tests falling along a spectrum, with unit tests (those that test just enough) on one end and the functional/acceptance tests (those that test too much) on the other.

Each test along this spectrum is important but the speed and quality of these tests will be one of the factors that determine how fast you can change or add to your code base. By all means, slower, bigger tests further along in the spectrum can be substituted for faster, lighter unit tests, but its consequences usually lead to a project that is less agile and more waterfall-driven.

Here are a few signs that your tests may be masquerading as something more than just (better, and faster) unit tests:

• Your application must be �deployed� to run some of your tests;
• A user must interpret console output or some other type of result for the test to fail;
• Each test takes too much time to run (it should be possible to many of these within a second);
• Excessive amounts of set up are required for each test (a smell that this might be integration test and/or testing too much); and
• Tests cannot be run without some external resource (such as a database, specific computer or some file);

Why did the latest JDK have to go and copy C# and name their language feature Generics when it looks like this:

List<string> notSoGenericListOfStrings = getInitialListOfStrings();

I hope it’s not just because the implementation happens to lose all of that compile time information, making each strongly typed element the lovely generic java.lang.Object. After reading the reasoning behind its implementation and appreciating some of its motivators, I’m sure it will be all the more be interesting resolving any Reflection or AOP bugs in the future.