What is a Good Design?

Well, let's ascertain that with a thorough review.

Design Reviews

This has been one of my repetitive tasks for last several years and I have not been able to automate it. The reason is obvious, so far there is no tool in the market that can read & understand designs.  So I decided to make my life easier by making a checklist for it. And hopefully of others who happened to read this.

Most of the projects that come my way for a design review are web based distributed applications that integrate with several backend systems whether legacy or open.

Note: The points discussed below assess the quality of the design not the documentation quality.  When reviewing the design it is very important to keep the focus on the design and not the cosmetics of the documentation of the design. The cosmetics should not be given more that 10% of focus during the reviews otherwise it is possible to get distracted with the documentation of the design and lose focus of the design itself. This is a very important point that the reviewers need to take into consideration.

When starting design reviews the first thing that comes to my mind is, is this design following some architecture? So here goes the list of things that I look for to assess that the design is based on some well-defined architecture and not prepared based on whims. Things other than Architecture will follow.

Architecture Overview

A designer must have the architecture context in which the application is to be developed and therefore the design must cover the points below:

Review Item	Available?	Remark
Architectural Overview	Y/N	May include system context diagram, functional view, implementation view, deployment (logical) view etc.)
System Architecture Document available/ link in references	Y/N	Should include Vision, Requirements (reference will do), Goals, Considerations and Decisions (regarding styles, patterns and technologies) trade off analysis all the way to technology decisions and deployment architecture
Layers & Dependencies Described	Y/N	The application layers & dependencies should be present either in SAD or described in this section of the design.
Technology Stack (Products & Frameworks)	Y/N	Again this should be available in SAD if not must be addressed in this section.
High level components & relationships identified	Y/N	If the SAD has identified any major components then those should be known to the designer.
System Interfaces		This should include details as below for every system interface a) Protocols (HTTP, RPC, Web Service, REST, FTP etc.), b) Transfer Mode (synch / asynch) c) Message Exchange Pattern(Request-Response, One Way, Request, Ack, Messaging) c) Data Exchange format (XML, fixed length, RPC etc), d) Interface Technology  (Java / .NET / UNIX / Mainframe etc.)

Understanding of Non-Functional Requirements

As part of the of the awareness of Architecture the design must also focus on the non-functional requirements / systemic properties of the system under design and thus the design must cover at least the quantitative NFRs or SLAs such as those listed below:

Review Item	Specified?	Remark
Response times across pages / screens	Y/N
Concurrent user count	Y/N	during peak hours & off-peak hours
Total user count	Y/N
SLAs for all system interfaces	Y/N	Are there SLAs available for any external internal systems that the system being developed depends on? This will include both availability as well as response time SLAs
Scalability	Y/N	Growth in number of users or transactions to be supported over specific period such as quarter, year etc.
Throughput	Y/N	Number of transactions / requests that the system much support e.g. 2000 transactions per minute

Once it is clear that the designer is aware of the NFR and has/had access to the NFR specs during design; we have to ensure that it is addressed in the design. While many of the NFRs such as High Availability requires provisions not only in application design but also at the hardware or infrastructure level such as clustering. However since the focus of this blog is design, we will restrict the scope to Design.  I will discuss Architecture reviews some other day. Let’s see how we can assess the design on how it addresses implementation of some of the NFRs in the sections below:

Design for Performance

Review Item	Addressed?	Remark
Database Connection Pooling	Y/N
Caching	Y/N	Caching of expensive immutable resources if any
Http Session Management	Y/N
Instrumentation / Performance Logging	Y/N	This should be non-intrusive as in when using AOP or Proxies
Message Parsing Operations	Y/N	This will include online & offline users
SQL Query optimization		This should be addressed for queries which return large dataset or join many tables
Pooling		Expensive resources should be managed in a pool

Design for Security

Review Item	Addressed?	Remark
Authentication	Y/N	Design must address the authentication technique
Authorization		Design must be able to identify roles and handle privileges and restrictions that come with it
Data Confidentiality		Design must state how data in transit is secured so as to keep it confidential
Data Integrity		Design should address how it is able to prevent modification of data by vested interests while in transit
Non-repudiation / Accountability		The source of data must be recorded and the source should not be able to later deny the fact that data was changed by it
Single Sign On		How does the design handle SSO required if any
Cross Site Scripting		Design should handle this, if it’s a web app
SQL Injection
Other vulnerabilities		Every day new sceurity risks are identified and so an attempt must be made to address all those that were known at the design time.

Design for Reliability

Review Item	Addressed?	Remark
Exception Handling	Y/N
Error codes & message catalogues
External systems AVAILABIITY		If the system under development depends on any external / internal systems then
Replication & Backup strategies known / available
Distributed components provided		If the application is clustered then care needs to be taken that shared resources are exposed over remote interfaces & replicated across cluster e.g. distribted caching, in memory session replication

Design for Resilience

Review Item	Addressed?	Remark
Monitoring & Alerts		The system should have a monitoring system that watches for system or subsystem failures such as database failures, messaging queue failures or any dependent system failures such as Directory Servers etc.
Notifications of subsystem failures to clients / systems		In case of any internal failures, the client systems must be notified or else the client systems would flood the system under design.
Retries at regular intervals		In case the failure is due to some dependent system then the design must ensure that the system under design attempts to connect to the failed system at regular configurable intervals
Notifications of system restoration to clients /  systems		Once the internal failures are resolved the client systems should be intimated about the restored links

Design for Extensibility

Review Item	Addressed?	Remark
Use of interfaces & abstract classes	Y/N	To promote loose coupling
DI Container		Dependency injection or annotation greatly aides making the design extensible
Use of patterns like Factory, Strategy, Service Locator		If not DI at least standard design patterns can be used for ensuring loose coupling
Use of AOP		Using AOP many of the cross cutting concerns can be externalized from code to avoid hard coding

Design for Maintainability

Review Item	Addressed?	Remark
Logging	Y/N
Loose Coupling
High Cohesion
Depedency Injection / Spring framework
Usage of Standard Design Patterns		e.g. MVC, Factory
Usage of frameworks		Third part frameworks not only simplify the code but these also aid in making code maintainable as frameworks follow standard patterns and provide documentation for the features
Modularity		Packages & components clearly identified with relevent names
Component & layer Dependencies Described		This will ensure that the target componets can be modified in isolation of other components
Shared  components / classes (across use cases) identified / described
Best practices for each product and third party frameworks followed.		Example:  for Spring MVC, list down best practices for Spring MVC here and check (Y/N/NA) whether each id being followed

Design for Supportability

Review Item	Addressed?	Remark
Logging	Y/N
Message Catalogue
Exception Handling
Alerts & Monitoring		Interfacing component for alerts & monitoring tools should be provided

Design for Internationalization

Review Item	Addressed?	Remark
Message Catalogue	Y/N
Labels externalized
Static / Reference Data localized

Deployment Considerations

Review Item	Addressed?	Remark
Deployment of components on various nodes / clusters identified	Y/N	e.g. database node, app server node, web server nodes etc? This is helpful in making decision such as whether to use distributed cache.
Logical deployment bounaries identified		e.g. DMZ, cluster boundaries
Deployable files such as JAR, EAR, WAR listed on nodes?
Application processes indentified & localized to various nodes		e.g. JVM process 'java', number of application related processes on each nodes
Common Services Deployment		Common infrastructre service nodes such as Directory Services, SSO services, User Provisioning services etc listed?

Other Considerations

Review Item	Addressed?	Remark
Instrumentation	Y/N	Performance Logging. This is easy with DI frameworks such as Spring. You can do it non-intrusively i.e. without adding anything to the source code
Logging
Exception Handling
Transactions & Data Integrity
Concurrency

After ensuring that all non-functional requirements have been taken in to considerations during the design, it is time to move into the very heart of the design, for which the design itself exists i.e. the

Design for Functional Requirements

Review Item	Addressed?	Remark
Requirement / Use Case Traceability	Y/N	Each requirement / use case maps to a section / subsection in design document
Use Cases		Use cases documenting all the actors, alternate & exceptional scenarios
Class Diagram		All classes, functions & relationships must be shown. The diagram should also include exception classes & hierarchies. The list value objects / DTO, along with all its attributes must accompany class diagram. It is not necessary to show all value objects in the class diagram as it would add to the clutter.
Sequence Diagrams		The sequence diagrams must cover the alternate & exception scenarios of each use case.
External / internal systems		All external / internal system interaction must be detailed covering message formats, protocols etc.
Wire frames / screen / page design for all pages / screens provided
Screen / page to database mapping		Each field on every screen / page should be mapped to corresponding database table / column.
Data / field value validation across screens /pages

Database Considerations

Review Item	Addressed?	Remark
Database access details -  SQL queries, Stored Procedures or ORM classes and mapping	Y/N
List of all tables & columns
Relationship between tables - ER diagram		Ensure all primary, foreign kes and other referntial integrity constraints are addressed
User profiles & access control lists		The design must address where the user profiles & access control lists are stored and how this data is accessed.

If the design that was under review has provided a design level solution for most of the aspects listed above as applicable, then it can be considered as a good design.