Insights

I've been on a lot of projects over the years, and have seen patterns of good behavior and bad. I want to share some of my insights with you here.

Coding with Maintainability in Mind

Applications aren't just written once and then used forever without modification. They must be able to evolve. They may integrate with other systems. Users might need new features, or changes in work flow based on their day to day processes. Unexpected errors have to be fixed.

All of these things lead to one inevitable task. Some developer (often times not the same developer that created the application) will have to look at the existing code, figure out what it does, and modify it. If the application was written with this future in mind, modifications will be easier, faster, and cost less.

What do you do when coding with maintainability in mind? You give artifacts meaningful names (see Variable Naming below). You encapsulate functionality. You minimize and centralize integration points to other systems. You put meaningful comments in your code.

Encapsulation is great when you need to reuse a piece of functionality, but it's also great when you need to modify it. If the developer can look in one place where the functionality is defined and make changes there, it's far less risky to the stability of the application than making changes in multiple places.

Integration with another system is best kept at a centralized location (again, not all over the place). It's also good to keep it rather generic. If you write an interface from your system to the other, you should write it in a way that you could swap out the other system easily. For instance, let's say the application interfaces with some accounting system, then your company decides to go with a different accounting system. You should be able to program a connector to the new system using your existing interface definition, making little or no changes to that definition. Keeping the interface loosely coupled with your application makes maintenance an easier undertaking.

Commenting your code does not mean that you have to comment every line of code. It seems developers either don't comment enough, or comment way too much. A good rule of thumb here is: If it's just obvious, routine code that's easily readable, don't comment. If it's potentially confusing or you did something tricky, add comments to explain what you did and why you did it to a future developer, even if you think that developer will be you. Your future self will thank you.

Don't Reinvent the Wheel

Sometimes I get on a project with a group of people who have also done many projects, and for some reason it feels like nobody has actually done this before. We have to decide how to split up work, test, assign bugs—the entire process. If a process has worked for you in the past, use it. Don't waste time reinventing how to do a project. The only thing that should be truly new is the application you're trying to build. If you have ideas, methods, or components that have been successfully used in other projects and you need the same thing for this application, don't bother writing everything from scratch again (of course being careful about intellectual property). Leverage your experience. Apart from using new technologies, much of the project life cycle should be similar to other projects you've done.

Variable Naming

The importance of variable naming is often overlooked—largely due to developer laziness. An IDE (Integrated Development Environment) like Visual Studio will name some things for you, like "Button1" for example, when you create a button. This in turn might label its click event "Button1_Click". Don't stick with these names. I've inherited projects where developers named fields "hiddenfield" or "temp", or sometimes even just a jumble of letters that doesn't seem to have any meaning at all. Or, worse yet, it might look like it has a meaningful name, but it's just plain wrong; like when "customerList" is actually just one customer, or maybe it doesn't even relate to a customer at all. The business people don't know or care what variables, methods, classes, or files are named. They just care if the software works. The software can definitely work with poorly named artifacts, but there are hidden, costly consequences for choosing under-skilled developers.

When the same developer is asked to make a change the application at a later date, he/she may remember how it works and be able to make a change. But as time goes by without anyone looking at the code, proper naming of things becomes critical. Even the original developer might stare at the poorly written code and have to re-learn how the application works because it's not obvious. A completely different developer will walk into the same situation and have no idea why the code is even working. Time, effort, and money is wasted on maintaining poorly written, poorly labeled code. If I see a button with the name "AddCustomer", "btnAddCustomer", or "AddCustomerButton", I immediately have an idea what that button is supposed to do. If I see a button named "Button1" I have to take time to dig further. Chances are that if the button was poorly named, the code that is run when the button is clicked also has poorly named variables in it. This is a maintenance nightmare, and honestly, I see it all the time.

Choosing meaningful names for programming artifacts is really easy and doesn't take much time, but makes maintaining an application so much easier. Any other developer should be able to look at your code and get the gist of what it's doing immediately. This is fundamentally important, and the way that I do it.