Custom Application Development Best Practices

A colleague of mine read my recent post about code quality and reminded me of the first time he read my musings about code quality, and work habits. He pulled up a team Best Practices document I had written back in 2001 for one of our first .net application development projects, and it's great to see how much is still 100% relevant today.

Work Habits

• Do it now!

If you see a change that you need to make, it's best to do it right now! It is very unlikely you'll get a chance to come back to it later. Plus, other people will begin to code with your bad code/names/etc. and the change that is needed tomorrow will be bigger than the change needed today. If you cannot do it right now, add it to your task list (in Outlook) and set a reminder for tomorrow morning. That way you will have another chance at it.

• Finish one task before starting another!

In general, it will be much better to be 100% complete with one piece of code/functionality than 50% complete with 2 or 3. You are focused, and able to actually deliver a fully working, tested piece of functionality to the client, rather than having 2 or 3 half-broken, half-completed, half-baked ideas floating around. Note, this is a bit in conflict with the previous point, and that is a little intentional.

• Understand an entire function/process before editing it!

When you are about to make a change, enhancement, or bug fix to a routine, read it first. Understand what the code is supposed to do (hopefully explained in the comments at the top) and then how it is (or isn't) actually executing. Making changes with only ½ understanding is guaranteed to cause additional bugs that have to be fixed later.

• Keep it simple!

Keep your code as simple as possible. Keep it maintainable, readable, and easy to debug. Most of the time on our project(s) is spent in QA and debugging. Most of the project is fairly basic - read some data from a database, modify it, and write it back out. If we can do this 80% of the project simply and correctly we can spend more on the interesting fun parts. If we make it complicated and buggy, we will spend 120% of our time fixing this easy section!!

• Optimize at the end, after it works

Write clean and simple code. Understand what your piece of code needs to do, how many users will use it, and how quickly it needs to execute. Plan for this, and code for it. Make all your code work. Then find the slow spots and, if they need it, optimize them.

Eight years later I might choose to add bullets about automation or unit testing or investing time & effort in the software not the design doc but the fundamentals are still the same!

Code Quality and Software Metrics

All good developers have a sense for Good Quality Code. They may call it "clean code" or talk about it is easy to maintain. When code is not good, they talk about "code smells" or "ugly code" or that it is simply "unreadable". Good developers have this sense, even when "good" is not strictly defined and is not measurable. Good developers go out of their way to keep the code that they work on clean, maintainable, and easy to read. Because they know they (or one of their colleagues) will be reading that code sometime in the future trying to figure out what it does and why that darn bug has slipped in to it.

About ten years ago the book The Pragmatic Programmer recounted studies about the effect of visible defects (a broken window) and the way people behaved in terms of caring about their surroundings. The findings apply directly to software quality as the developers on a project typically look to the existing code base to figure out the style of code to implement. In the worst case, a developer will start a new web page, batch job, stored procedure, or other module by simply copying an existing one and hacking up the code to do the new feature. In a typical case a developer will look for references in the existing modules to see "how is that done on this project?" So leaving the "broken windows" in your code base quickly leads to more broken windows as the ugly code is copied or used as a reference and more windows are broken, more graffiti is sprayed on the walls. Once the code base is littered with this low quality code, it's hard for a developer without a very strong internal sense of what is good to tell what is considered good on this project.

By paying attention to the little details, by setting coding standards and making sure people follow them, by requiring intelligent, useful comments in each module describing its purpose the tech lead or the team as a whole sends the message that they want to work in a clean, safe, easy-to-move-around-in environment. They don't want to work in a littered, trashy, graffiti covered neighborhood with broken glass everywhere. They care about the quality of the code.

One of the things I love about using automated tools to check the entire code base, every build (or at least every week) and is that it makes it possible to check for all the little details every build. In most business applications it is rare for every line of every module to be code reviewed. With an automated tool, it's easy - in fact it's automated! Each build produces clear, objective metrics about the quality of the code base.

The benefits of paying attention to little details, of sending the message that you care about the quality of the application code ripple through the entire application maintenance cycle. Developers are more productive, because the code is easy to read and understand. New developers are able to learn the code base more quickly because the code is clean and commented. Fewer errors are made because methods are short and implement a single function in an easily understood way. Global state, side effects, and tricks are not present in the code to cause trouble when their use is not fully understood by the next developer to modify them. Bugs that do slip through or odd corner cases that seem to only occur on one server are easy to track down because the code base has useful logging, has defensive checks, has error handling with relevant error messages, and only uses data values near to where they are populated.

A powerful psychological benefit for good developers when using an automated tool is that the entire team can see the quality metrics - ideally published on a regular basis and taped up on the wall of the team room - and take pride in watching the quality level go up as new features are added andsmelly code is cleaned up. The team can know that not only are they making the application work today - they are making something of good quality that will keep working in the future.

Importance of Business Domain Understanding

As a "dweeb", I love learning about new technologies. New programming languages, new frameworks, new Open Source tools. I love talking with colleagues about how we can use these great new technologies to solve interesting problems Faster, Better, Cheaper in order to make our clients happy. When working with one of our Outsourced Product Development clients or speaking with an Business Information Services prospect about how Hadoop can be used to streamline content processing it sometimes seems like that technology is important in and of itself.

But, sorry to say, the technology is not important by itself. And being an expert in a given technology is not enough. The true value that a "developer" or technology consultant brings is the ability to solve business problems, often by using technology in innovative ways. In order to solve those business problems, you have to understand the business domain.

Having an understanding of the business, the associated terminology, how the business model works, how the business makes a profit, how the proposed solution will add to that profit is critical in making all the little tradeoffs that must be made each day while designing and implementing a solution. In our RIGHTLine(TM) software development process we identify the need to have Knowledge Acquisition as part of the software development lifecycle. It's not enough to document requirements in a Business Requirements Document, the people writing and reading the requirements also have to have a shared understanding of the context that the solution and the requirements apply to.

When you try to apply a more agile development methodology, with more decisions made by the developers during implementation, this knowledge of the business becomes even more critical. A quote from one of our clients summarizes this well, he wants to have "ad server developers, not Java developers."