I love a well documented API as much as the next developer. I also am fighting a constant battle to improve my JavaDoc skills, trying to write to the same quality that I see in many other projects. But is excellent documentation really enough? It can’t just be excellent when it’s written it needs to be constantly maintained to this same level over time.

It’s a pretty common occurrence that I can look at a section of code and find documentation that has nothing to do with the method it belongs to. The intention revealing name sounds nothing like the documentation which describes what it’s supposed to be doing. Somewhere in the mists of time, the intention of the method and the documentation parted company; it is documentation no more it is ex-documentation. The problem here however is that there’s nothing to catch this issue. If an extra argument is added, Eclipse might display a warning telling me it’s missing from the documentation, but the actual context of the documentation can be completely wrong and I am none the wiser.

Although this incorrect documentation may seem fairly harmless to some, the reason it was supposed to be there in the first place is to the give the user of the API information on the method contract and the expected outcomes. If this information is completely wrong however it introduces confusion and also potential misuse of the API. After much wasted time and several grey hairs later I recently filed a couple of JIRA reports about popular open source frameworks which did exactly this. After my code just didn’t work and the unit tests failed, it took me a number of minutes to realise that the JavaDoc description of expected events just didn’t reflect what was actually going on in the code.

One approach to solving this problem is to include the documentation in the frequent code reviews. Code that doesn’t have documentation or has incorrect documentation can’t be considered complete, thus doesn’t pass the review. Developers need to make sure however, that they treat the documentation with the same respect that they give to their code and their tests. When dealing with documentation I’d much sooner see a method with no documentation than something that is completely wrong. I do want a good level of documentation in the code I work on but there is a very simple rule; update it or lose it.

Infrequent Reviews

Many teams operate on a feature complete code review. At the end of the cycle of work, several developers sit down together with the author critiquing the delivered work. What often transpires here is that due to the huge mass of code delivered, the chances of a thorough review are rendered utterly impossible. The plethora of code makes it difficult to find a starting point and thus potentially problematic code isn’t allocated the time it necessarily deserves. Any potential recommendations that come out of this kind of code may never see the light of day given the pressing work schedule (if the code was complete why are the changes necessary?). Most importantly for the team, reviewing code so infrequently can lead to demoralisation of its members.

Code reviews may pick apart the authors code; code that they have potentially sweat and cried over (ok maybe not) and worked hard to complete. Does it really make sense to save up all the potential criticism and deliver it in one skull crushing blow? Even if the criticism is perfectly valid, nobody likes to feel good about something only for it to be completely torn apart. Developers complain when customers only let them know what they actually want when they see what they don’t, is the same really acceptable for the code? If infrequent code reviews aren’t the answer, how often can code be successfully reviewed?

Email Reviews

Some teams never let the author of the code commit it to the repository. Instead, they email the code (typically in patch form) to the code owner or one of the principal reviewers. The idea behind this approach is the patches are always reviewed prior to them being committed, and the developers can work productively only focusing on the task in hand. This process has the ability to ensure that every change is scrutinised and verified to maintain the high quality standards that are set down. Having had to work with a system like this in the past, I can honestly say that it was fraught with problems and was one of the most frustrating I’ve ever worked with (I was one of the principal reviewers).

The person applying the patch quickly becomes a bottleneck in the process, how long can people really wait for the patch to be applied? What should the patch reviewer actually do with the patch, make the recommendations themselves or send an email back to the original author to apply the required changes. If multiple people are working on the code base, the chances of conflicts increase. If the patches are applied in the wrong order or peoples timing is just plain unlucky, the person applying the patch has a multitude of problems to deal with. The version control system is full of only one persons name, thus making it incredibly difficult to track down the original owner of the change. Lastly should the worst happen and the build fail………………….. guess who’s change it was that broke it?

Frequent Reviews

People like to know what and how they are doing with their work. If infrequent code reviews lead to a big bang delivery approach, then frequent code reviews take the inverse approach of small nudges in the right direction. By applying these frequent reviews, developers can deal with smaller suggestions and recommendations early in their development. Instead of developers feeling they have completed something only to be told it’s all wrong, they can be guided along the process to ensure they arrive at a right answer. The most difficult question here is; how frequent is frequent? This is a very developer specific metric.

Some developers require frequent attention and when I say frequent I mean every few hours (or more!). As developers become more experienced, this frequency typically reduces until the reviewed eventually becomes the reviewer. Depending on the type of project however, it’s still quite common for very experienced developers to like frequent code reviews. If frequent reviews become very frequent reviews, you might have unwittingly found yourself participating in quasi pair programming.

Pair Programming

Pair programming is not only a great way to develop but also to implicitly review code. A second developer sitting at the keyboard provides instantaneous reviewing of code. The second developer not only reviews the code, but also looks for potential problems and improvements to the evolving code. The second developer isn’t always necessarily the reviewer, and roles can switch between either developer during the exercise.

Having someone take over the keyboard encourages the development to be of higher quality and a second set of eyes prompts the coders to produce good code (obviously given a good pairing of developers). This instant review and feedback can actually reduce the number of bugs introduced into the system. As several developers produced the code, it also means that the team is never reliant on a single developer to address a given area of code. Pair programming is an excellent way of developing an reviewing code, but it’s not without it’s problems with some people finding the feedback is just too often.

Summary

By reducing the time between code reviews, teams can provide better guidance about the eventual quality of code and prevent storing up potential problems. The less frequent the code reviews are the more problems (especially with less experienced staff) that occur. Developers want to feel like that are doing a good job and as such then need small bits of constructive criticism often instead of lots of criticism delivered all at once. Reviewing code is best addressed frequently, providing quicker feedback, and reducing the amount of rework involved. As a developers ability increases, these issues typically subside and they become active in reviewing other peoples code.

If infrequent code reviews are problematic, are frequent code reviews the key to success?

Test code is just as likely to contain bugs as the code it is supposed to be testing. After all, if the tests are just code, why wouldn’t it contain bugs. The possibilty of it containing bugs could actually be higher as it doesn’t have tests and in many teams isn’t treated with the same respect as the rest of the code. Tests must therefore be kept as simple and easy to understand as possible and employ the same tools and techniques available when writing tests as are used in the rest of the code.

PMD and FindBugs are great tools to identify potential problems within code, but I have only ever seen one project that applies them to the test code. PMD/CPD is a great tool to identify duplicate code blocks, but I have never seen a project apply it to test code. If duplicate code isn’t acceptable, why should it be tolerated in test code?

@Test
public void updateFirstName() {
    ...
    User updated = getUserById(expected.getId());
    assertNotNull(updated);
    assertEquals(expected.getFirstName(), updated.getFirstName());
    assertEquals(expected.getMiddleName(), updated.getMiddleName());
    assertEquals(expected.getLastName(), updated.getLastName());
}

@Test
public void updateMiddleName() {
    ...
    User updated = getUserById(expected.getId());
    assertNotNull(updated);
    assertEquals(expected.getFirstName(), updated.getFirstName());
    assertEquals(expected.getMiddleName(), updated.getMiddleName());
    assertEquals(expected.getLastName(), updated.getLastName());
}

Over time, tests will inevitably suffer from the same problems as the rest of the code. Tests become bloated, complex, duplicated and hard to understand if they are not maintained and refactored regularly just like the rest of the code. The potential problem with refactoring tests is that you are refactoring something which does not have tests to verify your changes, but testing tests is a controversial issue and can probably be better solved by conducting thorough code reviews.

Code reviews seem to be an underrated technique within test code. Having spoken to many other developers, the majority of them had never participated in any test code reviews, with only a small number having used this approach on several occasions. What makes this even stranger, is the fact that many of these developers do conduct code reviews on a semi-regular basis. This is somewhat anecdotal evidence, but it would be very interesting to see some real numbers on this subject. How many teams conduct thorough code reviews of tests and treat it with the same importance as the rest of the code?

Code without documentation is considered by many to not be code complete, but tests without documentation are a pretty common occurrence. Tests should be simple, which means documentation is not necessarily required, but does that same argument apply to the rest of the code? Tests can have intent revealing names which are sufficient in describing the intended purpose of the test and projects like TestDox can take this and turn it into readable documentation. Is this documentation sufficient, if the test fails, does it provide enough of a clue to what was actually being tested?

In the past I have found test documentation to be extremely useful when writting integration tests. This documentation described the tests not in developer terms, but instead in a use case form. By writing a simple parser, it was possible to generate documentation from the tests which would allow the QA team to understand which flows had been executed. More importantly, it also allow them to quickly understand what a individual test was doing when it failed. This documentation was written as an experiment, but it has proved extremely useful to both developers and QA when something goes wrong.

When writing tests, teams need to ensure they don’t neglect this code. Tests should be maintained, refactored, reviewed and measured to ensure the same quality as they would in the rest of their code. Tests are still code.

The term Refactoring is widely used throughout software development. Martin Flower is one of the primary documenters of refactoring, and popularised it in his seminal book, Refactoring: Improving the Design of Existing Code. Many people who use the word refactoring however, have never heard of the book and more importantly don’t have a clear understanding of what refactoring actually is.

Refactoring is described as; a disciplined approach for modifying code without changing it’s externally observable behavior. This approach is focused around applying small changes to the code, each of which maintains the existing behaviour. By incrementally applying a number of refactorings, the code can be modified in a measured and controlled manner. Extreme programming embraces this approach with a rule named refactor mercilessly.

Alistair Cockburn wrote; “What we want to express sits in a crack between all the words we possess”, it just so happens that for many people (including myself), one word that is readily available is refactoring.

Team leader: So what are you currently working on?

Developer: I’m just refactoring some code.

Team leader: Are there any particular refactorings that you’ve found useful?

Developer: Yes, I’m refactoring the code.

Team leader: No, I mean specific refactorings e.g. rename method, extract method, etc……

Developer: Yes I’ve been doing all that sort of thing.

Team leader: Have you any idea when you might be finished?

Developer: I’m just trying to get the code compiling again, this might take a few hours.

Team leader: Hmmmm ok, I’m presuming you’ve been reviewing, improving and running the unit tests frequently?

Developer: The code doesn’t have any unit tests, so there’s nothing to run.

Team leader: Do you think it might be a good idea that you write some before you start refactoring? How do you know that your code will work in the same way as it did?

Developer: Errrrr……

If changes are informal or ad-hoc, this might be acceptable, but this isn’t refactoring. If changes will take days or weeks, or the code is simply being rewritten this isn’t refactoring. If the code is just being hacked, this really isn’t refactoring. Changes made in a controlled way are much more likely to be successful, but again this doesn’t necessarily mean refactoring.

Refactoring is in many ways a victim of it’s own success. Many teams have found refactoring to be a successful approach to making code changes in the past, leading to many people discussing all code changes as refactoring. Sometimes this is simply due to a lack of understanding, other times it’s a lack of care and attention for the words being used. Sometimes however people use the word refactoring to give the illusion of making disciplined changes, whilst reverting to plain old hacking.

There is a common perception amongst some teams, that every code change is refactoring, “if you aren’t refactoring how else do you make code changes?” The truth however, is that not every code change is a refactoring, nor does it make sense it to be. Even if the code isn’t truely being refactored, it is still possible to adopt many of the activities associated with refactoring.

Changes made in a structured and disciplined manner, offer far more control and are therefore often far more successful. Important questions therefore need to be asked when changes are being proposed. Are the changes being made with the benefit of a suite of automated unit tests? Is each code change being kept as small as possible? Are the code changes being incrementally applied? Are the changes being continuously integrated? Are the IDE’s tools being fully leveraged to make changes easier? Do other developers understand the approach being used to change the code?

When making changes to code, it’s very difficult to understand the associated risks without a solid understanding of the approach being proposed. If a project is deemed to be too risky it might be postponed and rescheduled for a more appropriate time. To aid understanding within a team, instead of simply using the word refactoring to describe changes, developers need to fully understand the approach they are using. Are they answering yes to the important questions (outlined above), and more importantly, if they aren’t, is that acceptable?

If the actual approach is refactoring, that’s great! It gives other developers some idea about the way potential changes will be made, and the style of approach is well understood. It integrates very nicely with many other best-practices and structured development techniques. This can significantly reduce the potential risks associated with changes, thus helping prevent the introduction of new bugs. But it is also acceptable to make changes that aren’t refactoring, whilst performing many of the same activities. It is therefore vitally important that developers talk about changes in context, and make them in a structured and disciplined manner, regardless of the name being applied to the approach.

If you are refactoring great, if you aren’t don’t be afraid to use a more appropriate word instead!

Motivation behind the post:

Following a few comments regarding this post, I want to clarify the motivation behind it. I’ve known about refactoring for a good number of years, and I’ve also often claimed to be refactoring. Last week I found myself talking about refactoring completely out of context and I was basically playing the role of the developer in the mock conversation. I was claiming to refactor some code, but actually this wasn’t the case at all. Some of the code was rewritten, other changes were unstructured, all without the benefit of unit tests. By telling people I was refactoring, I was giving an impression of control where non-existed, I personally don’t see this as a good thing! In this situation, I believe it’s much better to come clean and admit you are making unstructured changes, and if possible rectify the situation.

Testing without refactoring:

Another point that was raised, was that I had suggested if you don’t have unit tests you aren’t refactoring. I don’t think I did suggest this, but I thought it was worth clarif
ying the point. It is completely possible to refactor without tests, but as many other people have commented, it’s dangerous, it’s scary, difficult and time consuming. This is obviously dependent on the nature of the refactoring.

If the refactoring is a simple rename method, it is typically assumed to be fairly safe. I’ve made this mistake before and broken code when making changes, simply because I wasn’t aware something was called by reflection. I’ve also broken Spring configuration because the AOP used method name matching. Simple changes can still break code, no matter how simple they are!

Refactoring and testing typically go hand-in-hand, verifying the changes that have been made. It is possible to verify this other ways, but if this is a manual activity it can be extremely time consuming.

Related Links:

After writing this entry, I discovered Marten Fowler documented this phenomenon in a post entitled, RefactoringMalapropism. For anyone that’s a fan of the semantic diffusion that Martin describes, I’d just like to add that this was written using an agile blogging technique .

Let me just start by saying, if you’ve got this far you really aren’t one of the people I’m talking about! Hopefully you’ll see this as a good thing .

A previous project I worked on was mainly composed of short-term contract staff. The project saw large staff turnover and the code quality was generally quite poor. Many of the developers simply weren’t interested in the project and why should they be? Team members that don’t have to take long term ownership of a project don’t really have to worry about it’s quality or longevity. They can stumble through a project putting in the minimum amount of effort required to get the job done. They can move onto a new project and leave behind all the problems for someone else. When working with transient staff, you just have to be pragmatic about this, it’s just life. Some of these staff will be true professionals and give a project their all, others won’t.

Now I know this sounds like an obvious thing to say, but when putting a team together, you need to hire developers who actually take an interest in what they do! Many people involved in the hiring of staff really don’t understand this, and instead focus on finding someone who claims to be buzzword compliant. Having the right skills is an obvious requirement, but this isn’t the only consideration that needs to be made. A large percentage of developers out there, just aren’t interested in the project they are working on and more importantly they aren’t interested in software development in general. The more developers I talk to and the more horror stories I hear from them, the more I’m convinced that these people are on the rise.

Developers that aren’t interested in what they do, don’t invest in themselves and don’t strive to improve not only their skills, but also those of their team mates. They don’t take pride in the code they develop, and a real danger if you work under a developer like this is that you will stop taking pride in yours as well. They will never read technology blogs or articles, they will never be found viewing DZone, TSS, infoQ and they will never pick up a technology book. They have no interest in development outside the hours of 9am-5pm and they probably never will. They are basically happy treading water, just getting by.

They are probably perfectly nice people and outside of work you might have plenty of things in common with them. In a workplace however, teams incorporating individuals like this are always fighting an uphill battle. The knowledge transfer will always be a one-way process. Opinions in important decisions will seem like a diversion from everything else they could be doing. The most reaction you’ll ever get in a discussion is a nod of their head or a shrug of their shoulders. In the past I’ve found this can actually be somewhat infectious and it gradually starts to have a negative effect on the entire team.

You’ve basically got the worst kind of code monkey. One that doesn’t really know what they are doing, doesn’t understand what they should be doing, doesn’t care that this is the case and just isn’t interested!

Now if you are a code monkey who’s happy hacking away for eight hours a day, you aren’t interested in what you do and you really don’t want to learn, that’s absolutely fine and good luck to you! In my experience however, if you want to build a team that’s going to produce a product of quality and longevity, you need to steer well clear of these people! These people will drain your other team members, slow you down and will generally cost you lots of money!

You’ll find these people everywhere. They’ll always be too busy to help, but they won’t be shy in asking other people to help them. They won’t want to develop things the same way everyone else does and instead they’ll develop their own style. They will never want to get their hands dirty and instead want to do the cool R&D jobs. When everyone is too busy to help, instead of rolling up their sleeves they’ll turn to the wealth of free labour on the Internet forums. The majority of posts on forums are from hard working developers, but you’ll also spot the other type as well.

So as a cautionary tale, if you have employees who fit this profile, do a quick search on the Internet for package and class names that match your project. You might find nothing, on the other hand you might find the original author of your code on an Internet forum. Why not contact them and offer them a job, you might as well if they are writing code for you anyway.

If someone really isn’t working out in the team, you need to do something about it. The longer this goes on, the greater the negative impact will be on the team. This can very quickly go from one problem to several. If there is a hint of promise at all in this developer (and as an eternal optimist I’d like to believe there always is), work with them to try and understand what the problems are.

Get them involved in the team: find something they are good at or interested in and try and develop this talent. Encourage them to go off and find out more about this and report this back to the team, make them feel important and make them the subject area expert. You need to do everything you can to make these people integrated and motivated. If nothing interests or motivates your developer you’re in trouble. If it doesn’t work out, in many cases it’s better for these people to do nothing at all, such is their negative impact on team performance. At the end of the day, do you really need people like this in your team?

When you are looking to hire new team members, you need more than just buzzwords. Go for the developer that shows real enthusiasm and interest in what they do. Go for the developer that’s contributed to open source software or forums to help other people out. Go for the developer who is willing to admit they don’t know the answer to your question, but they do know how to find it. Go for the developer that asks questions and has opinions on things that matter. Go for the developer who is excited that you have a library of books for them to read. These are the people you can work with, you can encourage and you can help to become better developers. These are the people that will be an asset to your team and will help you become a better developer as well. One developer who’s passionate and highly motivated, is worth so much more than a bunch that aren’t!

Above all else, avoid the contradiction of the developer who isn’t interested in development.