Document Non-functional Requirements

Daan De Brouckere — Mon, 07 Jan 2008 16:56:00 GMT

When a new solution is being discussed, it’s easy to focus on all of the things it should do, what it should look like, and what technologies it should be based on. It’s very easy to get caught up in discussions with business resources about comprehensive feature sets and ways to present the information to customers. With a technical audience, it’s entertaining to squabble about the pros and cons of using one technology versus another to address the functional needs of a business problem.

When do discussions about disaster recovery, performance and scalability come into play? When should they? Why can’t I just say that the system shouldn’t fail, it should be fast, and it should be able to scale? The short answer is that this could be quite cost-prohibitive. The longer answers are below.

Let’s start with disaster recovery. I liken the conversation about disaster recovery to discussions about life insurance. To most people, it’s not fun to talk about what would happen if you die. Same goes for the brand new system you’re about to build. Disaster recovery is not a topic to be discussed AFTER the database gets corrupted or the application server CPU overheats. These are conversations that have to be had BEFORE the system is designed. Just as the functional requirements are documents, so should be these disaster recovery requirements. Based on different up-time needs and recovery efficiency, disaster recovery requirements could vary from making sure each server is backed up nightly to putting structure around a hot-backup on the other side of the country.

When it comes to talking about performance, the conversation tends to be easier; however, the proper documentation of performance requirements can be tough. How do you account for variations in network traffic? What if another process is running on your application server? The recommendation I have here is that you start by determining what an adequate response time looks like for the key functions in your new system. This needs to be balanced with the cost for delivering that kind of performance. Execute your performance tests in an environment that closely mirrors production. When it comes to documenting actual performance requirements, these can vary from a generic average response time per function to specific metrics around the key transactions of the system based on expected usage patterns throughout the day or during a specific time period (think concert ticket sales).

What about scalability? How do we expect the system to grow over the next several years? How many users do we expect initially? How many of them will be using the system concurrently? Even after having the answers to these questions (or best guesses), documenting requirements around scalability is difficult. I would recommend turning these into technical requirements around sustainable transaction throughput. Considering these requirements during the design phase allows you to build in the proper flexibility so the system can support the future anticipated growth.

Beyond these three different types of non-functional requirements, there may be many more that should be considered based on the system’s particular needs. The trick is to recognize early on in the initiation phase all the different non-functional aspects that are critical to the success of the system, documenting them, validating them, and ensuring they are written in a objective way.

Code Reviews and Maintainability

Mark Strawmyer — Wed, 26 Dec 2007 15:06:00 GMT

Its continually amazing to me how discipline can go a long way to helping ensure a solution has long term maintainability. Making sure you set parameters and agreed upon standards at the start of a project and then having the mettle to ensure that regardless of how tirelessly you're having to write code you take the time to stay within the parameters. More often than not when I'm reviewing a solution I see a lack of standards or consistency and excuses such as "there isn't time for it" is almost always the explanation offered or implied. Or even more shockingly you find an experienced developer that is coding with discipline, but not caring that others aren't and not sharing their best practices. Open forum peer reviews and discussion of code is something I am a big proponent of in projects especially early on. It helps ensure that folks are on the same page in terms of style, practices, and that the solution is getting off to the right start. This is great for reviewing key and common elements of a solution even if it is only practiced early in the project and then abandoned as the project is more mature in the lifecycle. The downside though is that it isn't realistic to expect that all code can be reviewed by such a process as there is often way too much code.

Enter tools. Even if there are no explicit standards being followed, there are code analysis and metric tools that can be a big help to making sure the overall solution is more maintainable and performant. Code analysis will examine the code and look for situations where items may be less than optimal or could be done another way for better performance, maintainability, security, etc. Common situations are things such as over use of string concatenation where specially designed and class library provided string building objects would be better or inconsistent use of naming conventions.

Code metric tools will examine things such as the overall number of lines of code, depth of inheritence, and cyclomatic complexity which is the number of branches that can be taken within a specific block of code. The higher the cyclomatic complexity the harder it will be to unit test the code as there are more conditions to test.

There are a number of tools out from vendors such as IBM (Rational), Compuware (DevPartner), and Microsoft (VSTS). Microsoft recently released the Developer edition of its Visual Studio Team Suite that now includes code metrics and analysis. I've been experimenting with it and using it to look at a bunch of different code and I've been pretty happy with it and its ease of use and understanding so far.

I highly recommend that developers and development teams adopt a tool to help automate code reviews and perform code analysis and metrics if you're not already. Even the most disciplined developer will benefit from having an automated review of their code. It only takes a couple of minutes based on the tool and size of the code base and the results can give you plenty to think about and decide to take action on or not. Its a great way to learn additional best practices you may not have been aware of by examining the output of the automated review. Each developer should be responsible for running such as tool against their code and remediating issues prior to having flagged an item as complete. Again, it is a decision making process as you won't want to blindly make all changes suggested, but such a process prior to turning in code will go a long way to helping overall maintainability.

Crowe Solutions Architecture Blog : performance

Document Non-functional Requirements

Code Reviews and Maintainability