How I handle web project hand offs

It's time to hand over a project. What do I provide when handing off a project? What do I expect to get when jumping into an existing project?

It's the same regardless of which side I'm on. Here's what I review and use to asses projects. I mainly deal with web applications, so I'm focusing on those.

Not everything here is necessarily part of the project requirements or agreement, but these are areas I look at to get a clear understanding of the state of the project.

What areas should I review?

I want to get a good idea of what's done and how to move forward. Can I deploy the code? Do I have access to everything I need? What might come up that wasn't thought about initially?

I want to know about:

• Documentation
• The code
• Hosting and infrastructure
• Compliance concerns

Documentation

After the developer (or team) leave, documentation will the first place to look for getting anything done. There are three areas of documentation I focus on.

How is the system built? Architecture documentation

This gives an overview of how the system is built. How and what does it interact with? What services are used and how do they communicate with each other?

I like the C4 Model and will often start here when developing systems. The C4 Model is like a map of the software. With each "C" zooming in for more detail.

I'm not sure how popular this model is, but having some documentation that addresses these different levels in important to understanding the system.

System Context is the top level view and gives an overview of the system. Who and how it interacts with. Who are the users? What are the other systems it interacts with?

Container is the next level down. I think of this as the system overview. It's job is to provide detail about the components in the system. How they interact. What they depend on. This is the most helpful for me.

Component details the a component described in a container. This is often an application and describes the code level areas. These are also very useful.

Code in the C4 Model, is UML diagrams of the code. These can be helpful, but often are overkill and fall out of sync with the code. I prefer to skip this as UML, and focus on documenting the code using comments as needed.

While not covered in the C4 Model, I like to review an Entity Relationship Diagram, ERD, to get an overview of the database architecture. These can be generated by some databases, but even a high level ERD is helpful.

How do I get code into production? Deployment documentation

I need to know how to deploy code after the hand off. This can range from simple to complex. Either way, documentation detailing how to deploy the code should be provided.

What is going on? Code documentation

Code documentation can be subjective. I believe code comments should highlight non-obvious code and decisions. If the comment repeats what the code does, it's not helpful. I could argue it's harmful.

Good comments highlight the why in the code. All systems I've worked on have areas where the why is important and not obvious. That's the kind of comments I look for.

Is the project done? QA

I want to know if the project is done. Done in the sense that functionality in the agreement is there and working. Has there been any QA effort? If so, have all the issues been resolved?

Code!

This is where I'm going to spend the most time. I'm going to read thought the code and tests, run the tests and the system, note open source libraries used, and look at security concerns.

Does it run?

I want to be able to run the system locally. Meaning I can build the software on my computer and run it. See it in action. This is important because, to make changes, I need to be able to run it.

Hopefully automated tests were part of the requirements. If so, what kinds of tests? Unit tests, integration tests, system tests? What's the amount of code the tests exercise?

Do the tests run successfully? Again, this is important for making changes to the code.

What's the code look like?

At this point I'll start reading though the code. One of the first things I notice is how the code is organized. Is it obvious where to look for functionality? Is the project using a Framework? Is the code well formatted and consistent? Are the helpful code comments? Is the code simple or is it using confusing language constructs?

Coding standards

Code should be well organized. It should be obvious where to find code. If it's using a framework, the framework will often have established patterns for organizing the code.

I want to see consistently formatted code. Meaning there are clear conventions used in the code. From naming to intending, and in some cases general formatting. Ideally linting and formatting tools where used and configured in the code base.

Are there comments that explain the why or give context to the code or are they describing what the code does?

Are there parts of the code that seem overly complex or using tricky language? Sometimes it's a bad thing, sometimes it's good, but either way it takes some extra careful reading to figure out what the code is doing.

What does the code use?

I'm looking for what the code uses and interacts with. Databases, servers, services, APIs, and open source libraries.

These are dependencies and dependencies have costs associated with them. It's rare for web based systems to not have dependencies. They allow systems to built much faster.

Databases and servers

How does the system store data? Where is the data stored? What's the backup strategy? Data is big part of the value to a business. It can also influence a lot of design decisions.

What other services are required to run the software? Web applications generally require a server, like Nginx or Apache. They can also use servers for caching, search indexes, queuing, and messaging.

Services & APIs

What other services and APIs are used by the system. These are great way to outsource parts of a system that aren't core to the business.

Services might be email providers, like SendGrid. Or analytics and logging services. I like to identify these because they can be forgotten until something goes wrong.

APIs are often used to interact with services. They are more explicit in the code and provide functionally, that again, isn't core, but needed. Like sending an SMS, getting data, and connecting to other parts of the system.

Open source libraries

It's rare that open source libraries aren't used. It's important to know what libraries are used because their licenses can have business and legal requirements.

Most licenses allow use in commercial projects and require attribution in the code. These are fine.

Some require code that incorporates or builds on them must also be open source. The GPL license is the most common of this type.

How does the code perform?

While reading though the code I'll look for common performance issues.

N+1 queries are queries that have to go back to the database for each row of data. If you have a list of data that has 10 items, and each item requires two more database queries to display the required data, that's 20 database connections for the 1 initial list of data.

Non-paged data. While developing it's easy to forget that a list of data will grow large in a production system. To handle those lists paging is used.

JavaScript / CSS size can also get large in development and is easy to forget to optimize in production. These large files will impact performance and search engine optimization.

Those are some of the most common performance issues I see, but it's worth looking for other areas that might be problem.

Security

This can be a huge area of work. I'm not a security expert but I look for common issues. Using a service focused on security audits and/or pen tests might be a good idea depending on the business requirements.

I do look at API, service, and database tokens and passwords. These should be handled with an encrypted key storage or with environment variables. They shouldn't be in the source code unencrypted.

For web projects the OWASP top 10 list is a good place to start for the top security flaws.

Frameworks and libraries can help mitigate issues related to Injection flaws, Cross-site Scripting, and broken authentication. But it's important to keep the frameworks and libraries updated with the latest security fixes.

Where does the code run?

I need to know where a project runs, where is't hosted. I need to know where the domain name is registered, where the DNS is hosted, and where actual code is hosted.

The domain name

The domain name is the main entry point for web applications. Knowing where and who can access the domain name is important for security and keeping the system running. DNS is the system that translates a domain name into a server address. Generally DNS is hosted by the same service as the domain name, but not always.

Loosing control of either can be expensive and time consuming to get fixed.

Hosting

This should be covered in the deployment documentation. I make sure the credentials for the accounts are secure and owned by the business.

Generally there is one hosting provider, like AWS or Google. Some projects use a higher level hosting provider paired with a specific database provider. Like Heroku using MongoDB Atlas.

Security

Again, I'm not a security expert. There are basic areas to check and recommendations for further testing if required by the business.

I make sure the business is the owner and has the admin username and password for the domain registrar, DNS server, and all hosting providers. When available those accounts should require multi-factor authentication.

I like to make sure server access is limited to the people that need access. Checking SSH keys and SFTP access is a good place to start. I also review the user access configured on the hosting providers.

For complicated setups or where needed by the business, I recommend getting a security audit or pen test done.

There are so many areas regarding security, these are the bare minimum.

Compliance

I like review if the project needs to comply with regulations. Some are pretty universal, or getting there, like ADA, CCPA, and GDPR. Others are dependent on the business or functionality of the application, like HIPAA and PCI.

WAI-ARIA is the standard for web accessibility and helps address ADA requirements. A11y Project is community-driven effort to make digital accessibility easier.

GDPR and CCPA are concerned with user tracking and user data requirements. The most common thing related to this is the cooking warning that pops up on most sites.

HIPPA and PCI are extra requirements for health data and payment data. If the project handles that kinda of data, those regulations need to be taken into account.

Why do all this?

If I'm on the new team, jumping into an existing project, I want to know as much as possible about the project. While it's possible to dig through and figure it out, that's not efficient and some aspects are easily overlooked on larger projects.

When I'm handing off a project, I want the other new team to know what I know. I want them to get up and running, and feel they recieved a finished project. I want the transition to be quick and easy. I want them to feel they made a good investment.

I've been on both sides of project hand offs and done reviews for clients at Red27 Consulting. I've produced reviews like this, and more, for due diligence during investment and potential acquisitions. It's a lot of information to cover and varies based on the size and needs of the project. More information and detail has made thoes transitions successful.