The Challenges of Maintaining Successful Software Projects

Have you ever found yourself wishing that the software project you’re working on would hurry up and die? The trouble with successful software projects is that you have to keep maintaining the same codebase year after year, as it grows larger and larger. Rather than getting a chance to start afresh like you do with greenfield development, you’re forced to live with the architectural mistakes of the past, and work with legacy technologies. And that’s just two of the problems that developers working on successful software projects can run into.

Of course it is possible to evolve your codebase over time to fix the architectural inadequacies, and migrate to newer technologies. But it’s not easy, and it’s easy to become disheartened in the battle against mounting technical debt. My own experiences in this area led to me creating my “Understanding and Eliminating Technical Debt” Pluralsight course, in which I explain some of the strategies and techniques I’ve found most helpful as I’ve worked to keep some very large and successful software products as maintainable as possible.

Don’t Forget to Clean Your Code

I really love the idea of “Clean Code”. Keeping our classes and methods short, naming things well, and making sure our comments are actually helpful all makes a whole lot of sense. What’s even better about it is that its not a particularly complicated idea. It could be explained in a couple of hours, and even the most junior of developers shouldn’t have a problem grasping the main principles. It also doesn’t usually take too long to clean up dirty code. Rename some variables, extract some short methods out of long methods, and review the comments. The only slightly tricky bit is extracting a helper class out of a class that has grown too big.

So why don’t I write clean code all the time? Why isn’t all the code I’ve written since I heard about clean code a shining example of code cleanliness?

Well the brutal truth is, when I’m writing code, I’m not thinking about cleanness. I’m completely focused on what can I do to get the feature implemented. So at the point that I’m “done” in the sense of having working code and passing tests, my code is probably in a mess.

The trouble is, there is a huge temptation to skip the “cleaning” phase. After all, there’s always plenty of new development tasks waiting that I’m itching to get started on. But if we really believe that we spend ten times the amount of time reading code compared to writing it, then spending fifteen minutes cleaning our code before we move on will actually make us go much faster in the long-run.

Clean code is a habit you need to force yourself to learn. Clean before moving on to the next task. When the test goes green its time to clean. Clean before commit. If it’s not clean, it’s not complete.

PS: be sure to check out Corey House’s excellent Pluralsight course on Clean Code.

The Five Rules of ReSharper

I recently managed to persuade my work to get ReSharper licences for our development team. I’ve been using it since I won a free copy at Developer South Coast, and after being initially opposed to the idea of such a heavy-duty Visual Studio extension, it has won me over and I’m relying on it increasingly in my daily work.

Last week I ran some training sessions for the developers at work to introduce them to its features, but also to warn against some ways in which the tool can be misused. Here’s my top five rules for using ReSharper (or any productivity tool for that matter). Let me know in the comments if you have any additional rules you’d add to the list.

1. It’s Your Code

ReSharper can offer to delete unused methods or fields, or to refactor a loop into a single LINQ statement. It provides several automatic refactorings such as renaming things, extracting methods etc. On the whole these seem to be extremely reliable, and before long you’ll be triggering these refactorings without a second thought.

But when you commit, it is your responsibility to ensure that the code works fully. Of course, the best way of doing this is having unit tests that you can run, so you can prove that when ReSharper deletes unused code, or refactors a loop, that everything still runs as expected. If you check in broken code, it is your responsibility alone - you can’t blame the tool. ReSharper sometimes gets it wrong (especially when detecting “redundant” code), but it never forces you to commit to source control. It’s your job to test that everything is still working as expected before committing your changes.

2. They’re Only Suggestions

ReSharper has a superb way of presenting the issues that it has found with the source file you are currently editing, by presenting a bar showing where in the file various errors and warnings are.

If you manage to eliminate them all, you are rewarded with a nice green tick, telling you that your code is now perfect. But this can lead to problems for people with an OCD tendency. They become obsessed by an overwhelming desire to make all of the warnings go away.

What you need to constantly bear in mind is that these are only suggestions. And sometimes the code is actually better like it is. Resist the urge to make a change that you don’t agree with. If seeing the warning sign really upsets you then R# helpfully allows you to supress warnings by use of a comment.

3. Keep code cleanup commits separate from regular commits

Fixing up the warnings that R# finds is so quick and easy, that you can find yourself wandering through a source file fixing all its suggestions without even thinking about it. The trouble comes when you ask someone to code review your bug-fix. They end up having to examine a huge diff, mostly nothing to do with fixing the bug. The solution here is simply to keep your bug-fix changes and your code cleanup changes separate. Or at least restrict the code cleanup to the immediate vicinity of the bug-fix.

4. Avoid code cleanup in maintenance branches

If like us you have to maintain multiple legacy versions of your software then you probably have to merge bug-fixes between branches on a regular basis. For those merges to go well, you want minimal impact to code, and code cleanup (especially renaming things) can end up causing widespread changes which can make merges painful. So the approach I have adopted for our team is to make minimal changes to legacy branches, but allow the code in the very latest version to be cleaned up as it is worked on.

5. Get it clean on first commit

Of course, the ideal is that when you write new code, you implement (or suppress) all of the R# suggestion before committing to source control. That way my rules #3 and #4 become redundant. Make sure you set up a team shared R# settings file so everyone is working to the same standards.

Development process signal to noise ratio (a rant)

In the world of audio recording, maintaining a high signal to noise ratio (SNR) is vital. Signal is the singer’s voice; noise is the traffic on the road outside. Signal is what we want to record; noise is what we don’t.

Just as noise can get introduced at any stage in the audio recording process, degrading the signal quality; the software development lifecycle has many points at which noise can be introduced. The only difference is, that the signal is information rather than sound. In software development, signal is information that is of use to me; noise is information that wastes my time.

In the audio world, if the signal to noise ratio is too low, it becomes simply too difficult or distracting to keep listening. The same is true with information. A low SNR to ratio bores people into switching off.

Here’s five areas in the software development / business process that you need to watch your SNR in…

Meetings

As a general rule, I dread meetings. They get me away from what I would rather be doing (coding). A meeting is maximally useful if the information that flows within it is relevant to all those present. Meetings to tell people things they already know, or that they don’t need to know, or that only one or two people need to know, are invitations to daydream, resulting in attendees missing the little that could have benefitted them.

The worst offenders are the “weekly” meetings, or meetings that are required by some kind of process (“kick off” meeting, “release” meeting, “checklist checker checking meeting”). If you attend a 90 minute meeting with only 5-10 minutes having relevance to you, something is wrong.

Talking in detail through everyone’s weekly progress, or everyone’s holiday plans, or everyone’s tasks for next week, or every open bug, or every support case, is likely to be relevant only to the person who organized the meeting. For everyone else, the meeting SNR is minimal.

Documents

Software documents, particularly those created from templates, also often suffer from poor SNR. Instead of getting right down to business telling us the crucial facts, we have to wade through pages of boilerplate sections marked “Not applicable”.

In one company I worked for, there were several pages in every software design document we ever produced devoted to the utterly irrelevant topic of PCB layout. If the first section of your document that contains useful information is numbered 4.6.12.5, something is wrong.

Documents with low SNR actively discourage people from reading. And the less likely anyone is to consult your document, the less motivated you are to write good documentation, resulting in a vicious cycle.

Presentations

Presentations can have terribly low SNR. A favourite example is presenters who try to follow the rule that says: “Tell people what you are going to tell them, then tell them, then tell them what you told them”.

Fine advice, but not when they interpret this as “tell people that you are telling them what it is that you are going to tell them, then tell them that you are telling them the things you told them you were going to tell them, and then tell them that you are telling them that you have finished telling them the things you told them you told them you were going to tell them.” Instead, use your introduction to make us want to hear what is coming next.

As with meetings, any attempt to exhaustively cover a topic in a presentation is a mistake. Don’t show me every possible graph and chart from last quarter’s financial results. Don’t show me every feature and configuration option. Show me something interesting. Leave me wanting more at the end of your presentation, not praying for it to end.

Comments

Comments in source code are also prime offenders for low SNR. Comments that state the obvious, or are sources of misinformation soon train the developer to completely ignore comments. It’s like the boy who cries wolf. Soon no one is listening anymore. The one really helpful comment you write might as well be invisible. No one will read it.

Comments are like footnotes in a book. Most readers will pause to see what a footnote says the first time they encounter one. But if what they find there is of no relevance or interest to them, they will soon train themselves to stop looking.

Code

What about your code? Surely that is all signal right? After all, we can’t delete 50% of the lines and leave the behaviour of the code intact. But the truth is that code can be written in a very noisy way. This happens when so much code for logging, or caching, or error handling, (or whatever) is mixed in that the structure and intent of the method in question is obscured from view.

The solution is simple: write clean code. Extract each task out into small, well-named helper methods or dependencies. This allows people to see the “signal” of what is going on, and only delve into the details that are of interest to them. Implementation details are usually noise.

Summary

Stop writing comments that are just noise. Delete comments that are wrong. Refactor “noisy” code out into helper methods. Learn what clean code is. Hold fewer and shorter meetings. Write shorter documents. Tell me what I need to know. Stop wasting my time.