How to Evaluate a Code Base

One of the services we offer at Sonjara is the Technology Evaluation. Usually a client has inherited an existing website or application and they need an independent evaluation of what state it is in and what should they do next. Here are all the steps and stages of a technology evaluation of an existing code base.

Step 1: Understand the Project

Before we start the evaluation, we need to know as much as we can about the project, such as

• What is the goal of the software and does it currently meet it? All details on requirements for functionality and usage are important to be aware of.
• What is the history of the development of the software (multiple developers, one developer, etc)
• What are the gaps between what the software does now and what it needs to do?
• What are the future plans for the software? For the data it contains? Will it need to be migrated or archived? Replaced?

Finally, we also need to know the parameters of the evaluation.

• Are we giving an analysis of the code quality, stability, security, or other parameters?
• Is the assessment about the long term lifecycle of the project, i.e. what should be done with this code base/data?
• Is it an impact assessment of effectiveness of the investment at achieving the goals of the software?

Step 2: Access Existing Code base

Getting copies of whatever information we can gather is important. We try to get the original source code if possible, a copy of the database schema and at least a sample data set. in some cases, we cannot get the source code, so we may have to run the code through a decompiler and then reconstruct it into a development environment. Ideally, we would also have access to the production server, at least to see if there are any special configurations with the server we need to be made aware of.

Step 3: Determine Architecture

Once we have a good sense of what the site should do, and currently does, and we have a copy of the code base, we look at the documentation and code base to determine the software architecture method. What does the data model look like and how is data managed? Are there common functions?

A subset of this step is to determine the level of site conformance to that architecture. On organically grown sites, or ones managed by multiple development teams, we tend to find discrepancies between the architecture and implementation. The more work arounds put into place, the less the architecture is solidly constructed, and often we find many holes.

We also examine authorship of the code base. While every developer has their own signature in code, a well engineered site should have a level internal consistency despite many developers being involved. Less consistency between developers means that the architecture may have been undermined.

Step 4: Identify the Metrics of Evaluation.

We generally specifically measure the quality of a site based on the following criteria:

• Readability: how easy is the site for another experience developer to "read"- are functions well named, is there good commenting in the code base, is the code well formatted across different developers?
  
  
• Adaptability: how easy is it to make minor, common changes to the site? For example, how easy is it to add new fields to the database, add additional content or choices, or change the user interface?
  
  
• Maintainability: How easy is it to maintain the site on production, without outages, errors, or issues requiring a developer to get involved?
  
  
• Performance: How fast is the application? Does it hang or time out? Do the pages load in a timely fashion? Does it scale when loads get high or when running CPU intensive functions?
  
  
• Accuracy: Is the site capturing and displaying data accurately? Does the database have data corruption? Are there existing bugs in common features?
  
  
• Security/Privacy protection: based on the requirements, what are the security and privacy protections in place against unlawful access? Are there logs, password encryption, SSL certificates, or separation of personally identifiable information? Have common security processes been implemented against common hacking vectors, such as sanitizing your inputs?
  
  
• Interoperability: If the data in the database either needs to migrate to a new system or be exported/exposed to another system, is the data model structured in a way to make this easy?
  
  
• Usability: Is the site easy to use by core users, including the site administrators? Is the site optimized for the most common users? Are there common data validation tools to avoid bad data entry (such as requiring date formats?) Does the site conform to common standards of user interface design and accessibility? Does it look professional and trustworthy for the audience?
  
  
• Software Engineering Process: Is it clear that the previous team used standard software engineering processes such as version control, change control procedures, a testing framework for security, load, cross browser compliance, and 508? Is the code documented and is it updated? What is the process for database management for the production environment?

Step 5: Determine Recommendation Parameters

Based on Step 1, we should already know what the goals of the evaluation are. We also need to understand what the expectations of the client are for past decisions.

We try very hard to not bias the evaluation by either being too hard or too lenient, and instead base it on the goals of the evaluation. 

There can be a tendency for any developer to dislike another developer's code base because "I wouldn't have done it that way". We also know that best laid plans are thwarted by small budgets, unexpected changes, contradictory client guidance, staff turn over, and the fact that everyone hates to document their code.

We don't expect perfection in code, but rather 'good enough to get it done according to requirements'. Our metrics above are based on our experience of what makes code solid; no-one's code will ever be perfect according to every single metric.

Step 6: Make Recommendations

We start by looking at what is working well according to the goals of the site. These features need to be protected or carried through to the next iteration.

We then find the places where the current structure doesn't meet the requirements (either current or anticipated future ones).

Based on the requirements for the evaluation and for the software, we then rank the gaps based on importance for the client.  For example, for a website that has been inherited by a new team and needs some changes to it, we will focus on recommendations that address immediate needs, with other priorities (about scalability or long term performance) lower on the list.

Our recommendations for changes usually are based on the question of "fix or replace". The recommendation is based on the project lifespan; a project that is winding down and has less than a year left, it makes more sense to fix and make do, than to replace the entire system. On the other hand, a vital element of your company operations that generates revenue? yeah, you may want to replace it from scratch as the expected rewards of a new system (new features, lower maintenance costs, etc) may well outweigh the costs.

Conclusion

Our goal in any of these technology evaluations is to give our clients information on the best next steps for technology they have inherited or own. Getting an independent set of eyes from people who have managed and built hundreds of websites and applications over the past two decades can be invaluable to determine where to put your resources.