One of my pet peeves in programming is that few people use guard clauses. A guard clause is an almost trivial concept that greatly improves readability. Inside a method, handle your special cases right away and return immediately.

Have a look at the following example:

private int doSomething() {
    if (everythingIsGood()) {

        /*
         * Lots and lots of code here, but that's a different story.
         */

        return SOME_VALUE;
    } else {
        return ANOTHER_VALUE;  // a special case
    }
}

You can easily rewrite it using the Replace Nested Conditional with Guard Clauses refactoring from Martin Fowler’s Refactoring:

private int doSomething() {
    if (! everythingIsGood()) // <-- this is your guard clause
        return ANOTHER_VALUE;

    /*
     * Lots and lots of code here, but that's a different story.
     */

    return SOME_VALUE;
}

Once you’ve read past the conditional(s) at the beginning of the method, you know that your world is in order and you don’t have to worry about special cases anymore.

In my projects, I’ve always been the one who took care of infrastructure, standardization and quality assurance from the development perspective. The funny thing is that I’m no admin and no QA guy, so most of it wasn’t even my job. In this article, I’m going to list a few things that in my opinion as a software developer are essential to a professional software project.

What you need is no secret: If you read a few books and follow some technology blogs you know the bits and pieces. I’ll list a few things from a Java/Maven perspective, so some of this may or may not apply to other platforms.

First of all define a common coding style. I shouldn’t even have to mention this, but there will be chaos and conflict among developers if you don’t have it. Just use Sun’s Code Conventions, make some exceptions like “maximum line length is 120 characters” or “no tabs allowed” and you’re halfway done. Provide a bit of example code (one class, one page of paper) and put it up on a wall. This style guide should include rules for things like logging and exception handling strategies as well. Too few developers are even aware that you need a strategy here, so write it down! Don’t forget to define package namespaces for your project.

For Java projects provide organization-wide Maven archetypes that give you a solid basis for your project. Use existing open source ones to get you started! The effort for this pays off with each new project in reduced setup costs. But wait, each of your projects is different? Oh please, then adjust your build scripts. That’s no excuse to start from zero each time!

On a related note, invest in a proper internal Maven repository setup. Maybe use a stripped down version of Atlassian’s setup. You don’t want your builds to break just because some external repository isn’t available. Define rules who may deploy what to your repository. I’ve seen a lot of chaos here, so remind people to actually think before deploying stuff and breaking builds.

Get yourself a proper bug tracker and define how you’re going to use it. It doesn’t have to be fancy, a Trac installation will do in most cases and it will give you a wiki for your technical documentation, too. Do you just track issues or also tasks for developers? What’s the workflow? Who may open a ticket, who may close it? What amount of testing is required?

For god’s sake, define rules for working with your revision control system. How often should developers check in? How should a commit message look? How does your release process look like? When do you create a branch, how are releases tagged etc. Read up on the features of your system, branching may no longer hurt. Move on if you’re still using CVS.

A professional software project needs continuous integration. Period. Set it up (I recommend Hudson), define the proper reports and actually read them. It’s crucial to check test coverage and other metrics right from the beginning. If you add reports later, you will typically get warnings for every other line of source code. Nobody will read those reports anymore and it’s too much work to clean up the code.

Provide developers with a proper workstation setup that corresponds to the platform you’re targeting. Yes, it’s a good idea if everyone on the project used the same JVM and application server versions. If that’s what your production environment uses, even better! It might improve the chance that things actually work. Just saying.

I’m barely scratching the surface here, but it’s enough for one article already. For many of the points above you can find articles on the web (check my blog’s best practices category, for example). And still, it’s frustrating how little many software companies invest in those bare essentials.

There are many ways to store session data in web applications. They all differ in scalability, failover capabilities, and complexity. I’ll give you a quick rundown on the major themes.

Session Data on the Client

You can often implement simple personalization features or workflows by storing state on the client. From a scalability point of view, it doesn’t get any better than that. Not having to keep state on your servers saves you from a lot of trouble.

Cookies are a well-understood mechanism that can even be used in a client-only manner using JavaScript. They are useful for small portions of data that aren’t security relevant. Informal polls or simple preferences like language selections are often implemented via cookies. Cookies also play a major supporting role in user tracking and identification, but that’s a different story.

Some frameworks save workflow state in hidden form fields (see Apache MyFaces). That data can be encrypted by the server to prevent tampering.

Session Data on Your (Web-)Servers

For many developers, saving sessions on the front server (which is often a web server) is the most natural choice. That’s what Java Servlet implementations usually do.

As soon as you need more than one front server, things can become quite tricky. Your environment may support some kind of clustering that provides session replication and failover. No matter which front server gets a request, the session data is already there or will be requested on demand. Depending on the implementation, a failing front server doesn’t necessarily mean a loss of session data. Apache Tomcat has this feature, as do commercial products. As powerful as this may sound, the approach comes with a rather large price in complexity.

Fortunately, there’s an easier way: sticky sessions. Your loadbalancer (a HTTP reverse proxy) assigns a cookie to each client on its first request. The cookie determines which front server subsequent client requests are directed to. That means, each client is always directed to the same front server, so session data for a client is only needed on one front server. As a result, you don’t need replication anymore.

The sticky sessions approach is easy to use but it has two disadvantages: First, if one server crashes, you will lose part of your session data. And second, load balancing may no longer be optimal because it is done on a session basis and no longer on a request basis.

In the Java EE world, session state could also be stored inside the application server (as opposed to the Servlet container). For example, the Seam framework stored conversational data using stateful session beans at some point. I don’t know if this is still common practice.

Session Data Inside Your Database

Saving session state inside the database is common in lightweight web frameworks like Django. That way you can add as many front servers as you like without having to worry about session replication and other difficult stuff. You don’t tie yourself to a certain web server and you get persistence and all other features databases provide for free. As far as I can tell, this works rather nicely for small to medium size websites.

The problem is the usual: The database server may become your bottleneck. In that case your best bet may be to take a suitcase full of money to Oracle or IBM and buy yourself a database cluster.

Using a Dedicated Session Store

Sometimes, especially for high traffic web sites, it makes sense to store session data on a dedicated server or cluster. This takes complexity out of your web servers at the cost of an increased overall system complexity. No matter what the SOA guys say, distributing your data usually won’t make things any easier.

If, for example, you’re currently storing sessions inside your application’s database, you could move the session store part to its own database. That’s about as simple as it gets.

I’m not aware of any off the shelf products, but since storing session data is typically not the most difficult problem, you could try to roll your own based on a caching product (memcached comes to mind, as do at least a dozen Java caching solutions).

If you’re particularly ambitious (traffic-wise), using a data grid like Oracle Coherence is a solution to consider. They come with everything you need to implement a high-performance distributed session store. And then some.

Conclusion

Use cookies for small pieces of possibly long-term data where security is not an issue. Cookies can also complement other approaches.

Otherwise, use whatever your web development framework offers. Sticky sessions are a powerful but simple solution when you’re starting to scale out your system. I wouldn’t turn to session replication if I could get away without it.

If things get rough, a dedicated session server or cluster may be your last chance. But then you shouldn’t be needing my advice anyway.

For further information see Martin Fowler’s Patterns of Enterprise Application Architecture. It has a short section on session state patterns that covers client, server, and database session state.

Development environments and their configuration can become quite complex. It’s not unusual that a complete workstation setup takes half a day or more and requires extensive help from other project members. Using virtual machines for the runtime environment can help to reduce setup and maintenance costs.

For large Java web applications, you often need to set up a database server (with a suitable database snapshot), an application server, a web container, maybe a frontend Apache server and other components before writing the first line of code. Every new developer on the project has to go through this exercise and everybody has to keep the system current. More often than not, each system is a bit different, especially if developers use different operating systems or work on multiple projects with each having its unique set of requirements.

The idea to end this pain is simple: Create a virtual machine image that is as close to the deployment environment as possible. Install everything necessary to run your application. Set up bridged networking (as opposed to NAT) to make your network stack available from the host machine. Depending one your local network setup, you might be able to use DHCP and central user management. Things aren’t exactly trivial here, but a good sysadmin should be able to help. The good news is that you only have to do this once and the base system can be reused for other projects as well.

Development takes place on the host machine, so developers can work with their favorite operating system and IDE. Each developer gets a copy of the virtual machine image (the application runtime environment) and can start working in no time. You build the application locally on the host system and deploy it to the virtual machine using a network share. That way, you standardize on the runtime side and people can still work with the tools of their choice.

Additionally, you can install the virtual machine image on a dedicated host to act as a central testing or demonstration system. You could even make your continuous integration system deploy to it, too.

Just try it, the little bit of extra effort quickly pays off.

There are millions of web applications on the Internet that are under constant development. Paying software developers to work on bug fixes and new features is quite expensive already, but what’s often neglected is the cost for deployment and operation. Well-run organizations invest in their deployment and runtime infrastructure and are rewarded with reduction of errors, shorter downtimes and lower costs in the long run.

Professional IT organizations run dozens of different applications on thousands of machines with a surprisingly small number of administrators. I’ve seen rollouts on 20+ machines during the day without any downtime; it’s just a matter of infrastructure.

In this article I’ll discuss some best practices I’ve learned in the field, concentrating on three important aspects: automation, monitoring, and standardization.

Automation

You should never need to ask yourself what it takes to roll out the latest release on production systems. Rollouts shouldn’t require arcane knowledge or lots of detailed installation instructions. In a good organization, there’s a general rollout process in place and things are automated as much as possible. A deployment process that involves admins doing an "svn checkout" in your web server’s htdocs directory and then manually adjusting configuration on each host is not exactly the most robust approach.

Your build system is the best starting point for improving things there. Provide a one-button build with different profiles for development, QA, and production systems. It should be absolutely painless to create a release artifact that relies on as little external configuration as possible. Don’t create a release from a developer’s workstation though. Use a dedicated, well-configured integration machine for that.

Usually it’s a good idea to store production configuration (maybe except passwords) in your source repository or configuration management database. You don’t want to lose your hand-crafted configuration if a machine crashes beyond repair. Release artifacts can be tarballs, WARs, ZIPs, even RPMs, but make sure you actually have a self-contained, versioned and installable artifact.

Installing the software on multiple machines has to work with as little human interaction as possible, too. Nobody should have to log into the box and fiddle with configuration settings. Write scripts and test them thoroughly so that people trust them. Robustness and transparency (in case things go wrong) are key here.

If you’re working with Java web applications on Tomcat, for example, why not use a fresh Tomcat installation for each release? Copy it to a new directory on the target machine, shut down the old server and then start the new server that already contains your web application. No cruft is left between installations, no long-forgotten configuration, no questions why one host works and another one mysteriously doesn’t. You might even be able to revert to an old release in case of trouble (unless there are DB schema changes or something).

Monitoring

No application will work indefinitely like it did when it was first installed. To provide a reliable service, you need notification when (not if) things go wrong. Fortunately, with tools like Nagios the infrastructure isn’t difficult to set up.

Noticing a crashed machine is good but certainly not enough. There are many things that can go wrong in your application even if all your machines are running happily. Meaningful monitoring works on the application level, too, and of course it is highly application specific. You could test if external resources are still available (like databases or web services) or if important use cases still work (like an ordering process). Careful analysis is needed here.

Your application has to provide interfaces to the monitoring framework so that regular checks of the application’s health are possible. The interface can be JMX-based or there might just be a web page with an easily parseable status format that’s only available from within your network. There are many ways, but the difficult part is to figure out when your application works perfectly and when it doesn’t. Typically, you want to be notified if a web application generates 4xx or 5xx pages above a given threshold. But be careful, attackers could use that knowledge to ruin your admins’ Sundays.

Standardization

Standardization is important if you’re operating many similar applications. You typically want the application running 24/7 and every sysadmin (even one who isn’t familiar with the particular application) should be able to perform the basic tasks like figuring out the status, fixing minor problems, restarting it, finding the documentation etc.

Good and simple things to standardize are the location of program and data files, configuration, and logging output. Provide documentation for developers to follow, or even better, provide a project template that already contains the framework that’s necessary to make an application blend into your environment nicely.

Work out a general deployment process to reduce the risk of rollouts. Even if you don’t have a dedicated rollout manager, you can still cut down the stress for everyone involved. Create a rollout plan for each release that contains all required information like involved people, affected systems, step-by-step instructions, expected effects and success or failure conditions. Don’t forget to provide a rollback plan in case the new release doesn’t work out as expected.

Creating a good user interface is no trivial task, no matter if it’s running as a desktop application or inside a browser. When it comes to accessing server-side resources (a common thing in the corporate world) web applications seem to be the first choice nowadays. You have complete control over deployment and in theory platform independence.

However, there are lots of disadvantages, too, and I don’t understand why the alternatives are so often not even considered.

When building a sophisticated web application, you always have to work around the stateless nature of HTTP, deal with browser quirks, JavaScript’s idiosyncrasies and other limitations. Sure, frameworks exist to hide all that from you, adding layers of abstraction and complexity. In the best case, web development feels almost like traditional client-side programming. The question is, why do we put up with this?

Don’t get me wrong, I’m not talking about classic web sites here. Not even about community sites where users generate content. I’m talking about all those countless in-house applications that are used for data entry or management. A good example are corporate content management systems: They usually come with a more or less sophisticated web UI, but the number of people actually being allowed to edit content is small (the deployment argument doesn’t work here).

In many cases, a rich client is a more suitable and cheaper solution. If your users are a relatively small on-site group, there should be no logistic problem to provide them with up-to-date clients. Technologies like the Eclipse Rich Client Platform (RCP) or Java Web Start for even easier deployment should be considered. I’m quite confident that they would help to reduce development costs quite a bit and (if done right) could result in a far more powerful and ergonomic user environment. In web applications you have to reach for Ajax (adding a second programming language to your project) and still won’t get anywhere near a classic desktop application.

Maybe the problem is that there are too many web developers out there …

Agile software development methodologies like Extreme Programming (XP) propagate collective code ownership: Every developer is allowed (and encouraged) to make changes wherever necessary. But is this really a realistic, useful approach?

The theory sounds compelling: Everybody knows their way around the code base and can work on anything. Without module owners, a potential bottleneck is eliminated and an absent programmer doesn’t block progress anymore. However, as I pointed out in the comments to this article, it all depends on your team.

When It Works

Judging from my own experiences, collective code ownership needs several preconditions:

• Team members are on a similar skill level
• Programmers work carefully and trust each other
• The code base is in a good state
• Unit tests are in place to detect problematic changes

If skill levels diverge widely, more experienced programmers usually won’t trust their less experienced colleagues. When code is modified, there’s always the risk of breaking things (and unit tests can only go so far).

But even if the environment is suitable, true collective code ownership is hardly realistic. In practice, there are always experts who are more proficient in some areas of the code. You can make changes there, but difficult bug fixes or major new features should be coordinated with them. Otherwise you’d just waste your time or achieve less than optimal results.

In XP, pair programming provides real-time code reviews that work as a safety net. As long as pilot or co-pilot know the code they are working on, major damages won’t happen that easily. However, if pair programming isn’t used, a different review technique is needed to catch mistakes early on. In some critical areas (ie. performance hotspots or security related parts), it may even make sense to prohibit changes without team consent.

When It Doesn’t

When skill levels or areas of expertise diverge widely, collective code ownership may not be your best bet. Experts will always achieve better results in their area and you usually don’t have the time to get everyone on the team up to speed.

With the collective ownership model, "broken windows" can be fixed quickly on the fly which helps to save your code from decay. However, if your code base is in a bad shape already and you don’t have a test suite in place to protect you from accidental damages, things are different. Strict code ownership will yield better results here since it’s less dangerous. The code may not be pretty, but at least some parts work and there’s no point in taking any risks, especially when you’re in a hurry.

Strict code ownership protects quality code against mistakes from weaker programmers leading to an encapsulation of bad code in a limited number of modules (quarantine areas, cynically speaking). With this containment strategy, you can direct debugging and end-game cleanup towards those problematic modules first since bugs have a higher probability to show up there.

Using CSV files in batch processing applications has many advantages, most prominently interoperability between programming languages and tools. One of its weaker points is data integrity though. The format has no way to declare data types or additional metadata other than assigning names to data fields using a header.

The simple metadata format proposed in this article can help to mitigate this disadvantage.

A Case for CSV

First of all, why would anyone use such a simple plain text format? After all it’s just a semi-structured collection of data sets.

Sure, CSV isn’t exactly the most sophisticated data format available, but it has many advantages that make up for this flaw:

• CSV is simple and well-understood.
• There are libraries available for many programming languages or they can easily be written.
• It can be analysed in a text editor.
• Samples of a file can be loaded into a spread sheet application.
• Files can be processed using standard Unix utilities.
• It is easy to split CSV files into individual, self-contained chunks.

See The Pragmatic Programmer, "The Power of Plain Text" (chapter 3) for a more detailed discussion.

Unfortunately, there are disadvantages, too. Parsing the file format is usually a bit more expensive than for carefully designed binary formats (though it’s much cheaper than parsing XML). And since the ASCII representation of numbers can easily be three times as big as the usual binary representation, CSV files tend to be rather large.

Fortunately, streaming compressors like GZIP typically reduces files to about 20% of their original sizes even on the lowest compression ratio. Compression saves disk space and network bandwidth but it comes at a slightly increased processing cost. In many scenarios, however, the added overhead is negligible compared to the cost of the actual processing.

Using a Simple Metadata Format

There are basically three places where metadata can reside:

• Inside the data file.
• As a file next to the actual data files.
• In a remote metadata repository.

If the data file format is extended to include metadata, we’d have to abandon the CSV format together with its advantages listed above. A remote metadata repository may be useful, but testing is a lot easier if you aren’t coupled to network resources, so a file next to the data seems to be the way to go.

The metadata format proposed here uses XML because it is human readable, well-understood and has excellent tool support (that should sound familiar). The format serves several purposes:

• It declares the overall representation of CSV files (field separator, whether compression is used etc.).
• It lists the set of files that make up the entire collection of data sets.
• It defines the data fields and their respective types.

Here’s an example of how it looks (see the Relax NG Schema for the semi-formal definition):

<?xml version="1.0" encoding="UTF-8"?>

<meta xmlns="http://mafr.de/ns/meta-0.1#">
  <file-location format="csv" compression="gzip" separator="\t">
    <chunk location="data_1.csv.gz" size="123456"/>
    <chunk location="data_2.csv.gz" size="34354"/>
    <!-- more chunk declarations ... -->
    <chunk location="data_N.csv.gz" size="7890123"/>
  </file-location>

  <data-fields>
    <string-field name="USER_ID"/>
    <string-field name="NAME"/>
    <continuous-field name="AGE" missing="0"/>
    <categorical-field name="COUNTRY" missing="?">
      <category value="DE"/>
      <category value="UK"/>
      <category value="OTHERS"/>
    </categorical-field>
  </data-fields>
</meta>

This format is pretty much self-explanatory, except for the data field declarations which use data mining terminology. The continuous type is for floating point numeric values, while the categorical field can be compared to enums in programming languages like C. The optional missing attribute defines how an unknown (aka NULL) value is represented. Of course, different and/or more data types with arbitrary
restrictions could be defined.

The data fields have to be listed in the order they appear in the CSV files. Reading applications may choose to accept any order though. Field names have to be unique and may not contain the field separator for obvious reasons.

Depending on policy, applications can either ignore unknown elements (or attributes) or flag an error. There’s also the option of declaring optional parts of the format in a different XML namespace. Some applications can use those elements while others may ignore them safely.

There are several ways of extending XML schemas, either by explicitly allowing unvalidated content (usually in a different namespace) or by including the basic schema from another, more specialized schema that extends definitions as necessary. Updating the base schema can be done via namespace and/or schema versioning, but since this isn’t entirely trivial I’ll leave it for a future article.

A Note on Container Formats

When you split your files into multiple chunks for parallel processing, you end up with lots of files. To avoid confusion and to simplify transfer between systems you might be tempted to use a container format that packages all your data into a single file (using tar, for example). This may work in some cases, but if your data files are large and created in parallel, the creation of the container is a long and I/O-intensive operation. In batch operations this causes a significant overhead that you have to subtract from your time window.

A compromise is to use a natural but cheap container format: A file system directory. It may only be a "virtual" container, but combined with a proper delivery protocol, it’s still useful.

The Delivery Protocol

If you’re handing collections of CSV files from one system to another make sure you follow a simple protocol: Copy the data files first and the metadata file last. The delivery isn’t complete until the metadata file is there. The best approach is to take advantage of the atomic renaming feature many file systems provide (see the rename(2) syscall on Unix). Copy the metadata to a temporary file and then rename it. That way the receiver will never try to read an incomplete file.

The Verification Process

With the information contained in the metadata file, it is easy to verify the CSV files as much as required. The most basic check would only make sure that all of the listed files are there and have the declared file sizes. A simple consistency check would parse the headers to see if all data fields are there. This would also detect if the field separator is correct.

The most thorough check would then go through all of the files and make sure the data fields match their declarations. Since this is extremely expensive, it should usually be a side effect of regular processing rather than an up-front operation.

Software developers often have to work with existing code bases, whether it’s for joining an ongoing development effort or for maintenance work on a legacy application. Getting familiar with foreign code takes time and can be a frustrating experience. In this article I’m going to describe my strategies for getting up to speed quickly.

Gather Information

First of all, get in touch with the people who know the system best. Especially those who originally designed and built it can often provide interesting insights as can people from IT or operations. Be communicative: Don’t waste your time struggling endlessly, ask for their advice on what’s important and what is not.

Make a list of all the information that’s available for the given system and find out what’s outdated and what is still relevant. The information you typically need includes original visions, business concepts, use cases, and presentations, as well as technical documents describing the architecture, subsystems, used patterns, or even key algorithms. Documentation may reside on file servers, wikis, source code repositories, internal content management systems, or just as printouts on paper. Try to get a comprehensive list.

Use a Top-Down Approach

Learn the system’s business domain, make yourself familiar with the overall architecture and have a look at how the domain’s concepts map to the software. Try to understand the general idea that’s behind the system and the kinds of problems it was designed to solve. Often that’s particularly difficult to extract from documentation. The most valuable information is usually in other people’s heads, so get them to share it with you.

Get a good understanding of the system’s environment: The kind of hardware it runs on, the number of users it services, the amount of data it produces etc. Get an overview of the most important libraries and frameworks the system uses. Usually it’s extremely helpful to understand its UI (if there is any) and its interfaces to other systems to see which services it provides and consumes.

As soon as you have worked through the high level architectural stuff, it’s time to check out the source code from whatever repository there is.

Get the Code Running

Set up a working development environment and make yourself familiar with the build system. Especially for older systems this can be surprisingly difficult: You might have to dig out ancient development tools because the newer ones are incompatible. Ask for assistance when you need it, it’s easy to waste a lot of time there. Make sure to document everything to save future team members the time and hassle.

Find out how to test the system. Go the whole way from running the test suite (if there is any) up to an end-to-end integration test. If there are databases or other dependencies in the development or testing environment see if they are still up to date. This is extremely important: If you fix a bug later, you need to be confident that the system still works and that you didn’t break anything in the process.

When maintaining legacy systems it’s often necessary to create a new release quickly after bugs have been fixed. Make yourself familiar with the release process, from both the technical and the organizational perspective and find out how the system’s deployment works. That’ll save you from nasty surprises when short response times are needed.

If your job is maintenance, you have to be able to react quickly to service requests or bug reports. First hand information is valuable, so try to get accounts for the production environment if possible. Access to log files and databases is very helpful as the operations or IT staff doesn’t always provide all the information you need.

Read the Code (Some of It)

Up to now I haven’t talked much about reading the actual code. That’s no coincidence because I think there’s not too much to gain, especially in maintenance of legacy systems. Even for small code bases it’s hardly feasible to go through the code and understand it all, line by line. That would usually just be a waste of time. Problems will likely turn up in areas you’ve never seen, so concentrate your efforts on understanding the organization of the code and a few selected key areas.

Often it’s helpful to pick a single interesting use case and trace it through the system at source level. Draw a few diagrams and ask your colleagues if they make sense. That way you’ll get a feeling for the architecture and implementation. At the same time you learn the coding style and conventions.

In an ongoing development project you’ll get down to coding soon enough. Writing a few test cases is a great help for getting familiar with the internal APIs. As soon as you feel comfortable (or maybe a bit sooner) get a few smaller assignments to dive in a bit deeper and read the related code as you go. It’s far more efficient than spending lots of time browsing through code at the beginning.

Share Your Knowledge

Getting into an existing project can be highly interesting: There is a lot to be learned even from the worst and most obfuscated applications out there. If documentation is bad you will probably need a fair amount of help from your colleagues. Don’t let it discourage you, instead make sure to write down your findings and use your fresh perspective to improve things. The next developer to go your way will love you for it.

Many software developers feel bad because they make little use of comments in their code. Often, using lengthy comments is considered good style. In the old days, with languages like C or assembler, things got messy pretty fast, so comments were the only way to keep track of processor registers or pointer arithmetic. In modern programming languages, more powerful abstractions are available. The question is, does this change the strategy of commenting your source code?

First of all, I’d like to differentiate between interface documentation and actual code comments. Interface documentation is often created from specially formatted code comments, but they aren’t comments in the usual sense. I’ll discuss interface documentation separately in this article.

In agile software development processes, you usually try to keep the number of supporting artifacts low. Lengthy analysis documents, fancy diagrams and the like tend to become outdated very soon as the code base is constantly being refactored. Updating artifacts takes time and discipline and you can’t be agile if you’re carrying around too much weight.

With comments it’s not much different. Although they live inside the code base, comments can be seen as artifacts, too. They have to be kept up to date and cause confusion if they aren’t. If a piece of code and its comment diverge, you can never be sure if it’s a bug or an outdated comment. In fact, the situation is worse than having no comment at all.

Based on books about software design (most notably: Martin Fowler, Refactoring; Eric Evans, Domain Driven Design) and my own experiences, I worked out the following strategy:

I try to avoid writing comments when possible. If a piece of code is getting complex and cannot be understood easily, I try to refactor it to make it simpler. Decomposing a method and using intention revealing variable and method names usually make the code easier to read. Only as a last resort, if a piece of code is inherently complicated, I add comments.

Generally, I favour comments on why something is done over those telling how something is done; it’s the code’s job to communicate the “how” part. Failed attempts and reasons why they failed are valuable, too, as they help a later maintainer to avoid old mistakes.

When it comes to interface documentation, I differentiate between private, public, and published interfaces. Inside of a class, where there are many small private methods, it’s hardly feasible to document everything. In-depth documentation would hold me back from necessary refactorings. Much the same holds for the majority of public methods, but I try to write at least a few sentences about each class, its purpose, and responsibilities.

Things are completely different with published interfaces. A published interface consists of all classes, interfaces, and methods (or other public features) that are to be used by external clients. I document classes, their invariants, method parameters, constraints etc. extensively. These interfaces typically don’t change a lot over time so the effort is certainly worth it. When published interfaces do change, it’s often a major effort that requires changing client code. In this case, an update to the documentation is unavoidable anyway.

Assertions are another useful way of documenting code. They can check pre-conditions and state the caller’s responsibilities at the same time. I run my test suites with assertions enabled to catch bugs but disable them in production environments.