Category: Code Complete

Architecture, according to the book (which draws from other sources as well), is:

Software architecture is the high-level part of software design, the frame that holds the more detailed parts of the design.

S. McConnell, Code Complete, second edition. Redmond (Washington): Microsoft Press, 2004.

Now that’s out of the way, let’s talk about how we can make sure that the architecture that’s laid out for our projects is good, since that’s what this chapter is all about. If your architecture is off at this stage, you’ll have to make the changes when you’re in the construction stage… That makes them a lot more difficult to solve, because you’ll likely have to move other things that you’ve already built around as you make the changes.

If you’re working on a system that was architected by someone else, you should be able to find the important components without a bloodhound, a deer-stalker cap, and a magnifying glass.

S. McConnell, Code Complete, second edition. Redmond (Washington): Microsoft Press, 2004.

The important parts of your architecture should be clearly visible. If it’s not clear why a class or component exists, or why it was chosen over other alternatives, then it’s possible it needs to be better defined.

Architectural Components

I was originally going to outline the different components and give a few details on each, but then I realized I’d mostly just be paraphrasing the book. Since there’s no need to do that, here’s a list of the architectural components, along with some of my associated thoughts.

• Program Organization
• Major Classes
• Data Design
• Business Rules
• User Interface Design
• Resource Management
• Security
• Performance
• Scalability
• Interoperability
• Internationalization & Localization
• Input/Output
• Error Processing
• Fault Tolerance
• Architectural Feasibility
• Overengineering
• Buy vs. Build Decisions
• Reuse Decisions
• Change Strategy
• General Architectural Quality

Now, it seems to me that a lot of these, such as the User Interface Design, depend a lot on the type of development that you’re going for. If you’re developing in a waterfall-style approach, then it’s great to have it fully defined upfront. However, I think that most modern software development occurs much more iteratively – so perhaps these should all be thought of in shorter iterations.

If you’re developing using an ‘agile’ approach, it seems like it’d make sense to have these things laid out at the beginning of a sprint. But it all depends on the approach you’re using. I know I’ve never used a strict agile methodology, so you have to apply this where you see fit.

This is covered a bit in the ‘Change Strategy’ point, but I still don’t feel like it fully addresses more iterative development approaches. It’s possible I’m just missing something, though.

Conclusion

Anyway, the point is that for any development, you definitely should have at least a basic architecture in place. Even if you’re developing iteratively, think through the things in the list above so that you can define an overview of the system before you put your fingers to the keyboard & start coding.

It shouldn’t look as if the problem and the architecture have been forced together with duct tape.

S. McConnell, Code Complete, second edition. Redmond (Washington): Microsoft Press, 2004.

Defining the Problem

Section 2 of Chapter 3 is very simple: you should know what problem you’re trying to solve before you try to solve it. It normally shouldn’t be stated in technical terms. Instead, it should be the simplest issue that you’re trying to solve.

For example, “We need developers to be able to parallelize their tests” isn’t a good problem definition, it’s already settled on a solution. “Developers’ tests take way too long to run” would be much better, because it states the problem, not a solution.

Defining Requirements

Section 3 covers devising the requirements for your software project. These should be agreed upon before work begins, and the customer should be the one in charge of validating the requirements.

Crafting well-defined requirements before starting the actual coding is important. It costs a lot more to adjust a design to meet new or updated requirements after code has been written than it does to just write the code to fit the requirements in the first place.

Specifying requirements adequately is a key to project success, perhaps even more important than effective construction techniques.

S. McConnell, Code Complete, second edition. Redmond (Washington): Microsoft Press, 2004.

But of course, requirements are rarely perfectly defined. It’s hard for customers (and developers, too!) to accurately describe requirements initially. As customers come to understand the system better, they’ll be better able to develop accurate requirements. So no matter how much we want things to be perfect the first time, it’s unlikely to ever happen in practice.

… the average project experiences about a 25 percent change in requirements during development.

S. McConnell, Code Complete, second edition. Redmond (Washington): Microsoft Press, 2004.

Dealing with changing requirements can be difficult, but it can be made easier by making it clear to your customer or client that changes cost, often monetary (though that depends on the type of project) and almost always in terms of time. If a customer is too happy-go-lucky with changes, establishing a change-control board to review the proposed changes may also be helpful (though I’d imagine that’s mostly where you’re doing client work).

One other important consideration is keeping the business reason for the project in mind. Oftentimes, you’ll find that features that sound neat or even necessary won’t be so important when you consider the main reason for the project.

Finally, this section concludes with a series of questions to ask yourself about your project’s requirements to ensure they’re solid. Reference the book directly for the list.

Different types of software require different types of planning. If you’re working on your own blog, for instance, the stakes are a lot lower than if you’re working on, say, an automated flight control system.

If you’re working on one of those high-stakes projects, your planning should be much more thorough & much less iterative. Your development is much more likely to follow a waterfall approach. But on your blog, or even something like an e-commerce site, you can (and arguably should) be a lot more iterative.

In either case, specifying more prerequisites upfront will help save time and effort in the long run, but it’s more important in more sequential projects. But, of course, your project’s balance between sequential and iterative will depend largely on what type of project it is and the risks involved.

One common rule of thumb is to plan to specify about 80 percent of the requirements up front…

S. McConnell, Code Complete, second edition. Redmond (Washington): Microsoft Press, 2004.

Essentially, you’ll need to pick the right balance for your project. If it’s something more stable, where the requirements are well understood and unlikely to change, a more sequential approach is appropriate. But if the requirements may change, or the structure isn’t as well understood, then a more iterative approach will be more beneficial.

Software being what it is, iterative approaches are useful much more often than sequential approaches are.

S. McConnell, Code Complete, second edition. Redmond (Washington): Microsoft Press, 2004.

For more details (as well as an analysis of the potential costs associated with each approach), check out this section of the book.

This is the second post in my series on Code Complete, covering my notes and commentary from Chapter 3, Section 2. The title of this section is Measure Twice, Cut Once: Upstream Prerequisites.

Essentially, this section is talking about the importance of developing prerequisites before beginning work on a project. It reminds me of a phrase that was apparently one of Frank Lloyd Wright’s favorites:

The architect’s two most important tools are: the eraser in the drafting room and the wrecking bar on the site.

Frank Lloyd Wright

In Software, this is equally applicable. The easier that we can catch defects, from design to development to production, the easier they are to fix. Obviously, in Wright’s quote above, using the eraser would be significantly cheaper than using a wrecking bar.

Much of the success or failure of the project has already been determined before construction begins.

S. McConnell, Code Complete, second edition. Redmond (Washington): Microsoft Press, 2004.

The diagram below is one that I created for a presentation given at Etsy – it’s a very generalized diagram, not representative of any actual set of data. However, it gives an idea of the relative cost to fix defects that are introduced during the software development process.

This section in Code Complete features a similar diagram – but backed by more solid data. Essentially, the earlier that defects are detected and corrected, the cheaper they are to fix.

…debugging and associated rework takes about 50 percent of the time spent in a typical software development cycle…

S. McConnell, Code Complete, second edition. Redmond (Washington): Microsoft Press, 2004.

So really, the whole point of this section is that planning reduces the overall cost of software development. Of course, this doesn’t mean that we should do everything in a waterfall approach and attempt to plan everything before we even start coding. We have to strike a balance between the two.

I believe, when using Agile methodologies, we should ensure that we plan carefully for the features that we’re focusing on building. Whether you’re using sprints or not, you can plan ahead for the work that you’re doing to ensure that you’re minimizing the ‘rework’ required.

It’s by striking a balance between planning too much and planning too little that we can be most effective in our software projects.

If you start the process with designs for a Pontiac Aztek, you can test it all you want to, and it will never turn into a Rolls-Royce.

S. McConnell, Code Complete, second edition. Redmond (Washington): Microsoft Press, 2004.