Performing a software code audit is a highly technical skill that requires expertise and precision. But without understanding the goals, cultural considerations, and overall state of an organization, it is difficult to have a successful outcome. When embarking on a code audit, it’s critical to keep the human side top of mind. Here are some ways you can do so:
Come Prepared
Code audits are often done within the span of weeks, which is not a huge amount of time to gather context from the often large number of stakeholders. So it’s best to go in with a plan!
If possible, get access to tools beforehand such as GitHub, Slack, and the team’s project management tool, and set up your local machine.
Once you understand the goals for the code audit, it may be helpful to spend some time up front creating a game plan for how to achieve those goals. For example, if you’re recommending how to best upgrade Rails, you may decide to begin by auditing test coverage and reviewing gems to determine any major risks.
On Day 1, it’s helpful to have a kickoff with stakeholders and to come with prepared questions. At thoughtbot, we ask questions like:
- What has been the life of this application?
- How is the team doing? Are folks excited to work in this codebase?
- What are the main friction points for your team regarding the application?
- What are the goals your team has agreed upon for this code audit?
Another critical point of this kickoff is to ensure you have a shared (and written down) definition of success. This will be an anchor you can revisit together throughout the code audit.
Stay Organized
Once you have defined success together, you should have a clear sense of your objectives. And if you have a tight timeline, it is helpful to spend some time up front getting organized.
- Timebox yourself for each project if there is more than one goal. For example, if you are creating recommendations for a Rails upgrade and determining how to improve test coverage, figure out how much time you’ll allocate to each goal.
- Book time with key stakeholders early on, as their calendars tend to get very busy.
- Schedule a recurring check-in to clarify goals as you make progress.
- Set expectations along the way. For example, if you’re meeting with the marketing team to help them assess extracting transactional emails, ensure that everyone understands that the goal of this code audit is a plan and not its execution.
Integrate With The Team
Code audits can be a scary initiative for development teams. They may wonder, “Are we doing something wrong? Are they trying to assess our code and tell us how to do our jobs?”
It is helpful to get in front of this type of anxiety. Be intentional about meeting with each team member and asking direct questions like, “How do you feel about us coming on board?” and “What do you think about the codebase?” These conversations help to put people at ease and give you key insights into the work ahead.
Additionally, while you’re working, be sure to elicit input from technical teams and present them with your findings before finalizing any recommendations. This helps to ensure that teams feel included and empowered, and that you are learning from the folks who have the most insight into what it’s like to work daily within the application.
Be Discerning
Oftentimes (but, of course, not always), teams that need a code audit have built up technical debt. This is sometimes due to competing priorities forcing tech debt to accumulate. In this type of culture, it can be easy to become involved in day-to-day development and to have code analysis tasks pushed aside.
But this is not in service of the team you’re trying to help! Deprioritizing tech debt is likely what led to this situation in the first place, and your goal should be to help the team focus on improving the quality of the application.
Additionally, code audits tend to reveal a broad spectrum of possible projects. Remember to be discerning and look for the projects that will yield the highest benefit.
Observe
A fresh perspective is often the best thing for a team. So now that you’re successfully interacting with the technical team and other stakeholders, you’re in a great position to help guide the more human areas of their business.
These could be process-oriented suggestions, like mentorship and pairing, or improvements to standup or retros. It could even be morale-related, like setting up a recurring team lunch or learning event. After all, these are the processes that most directly involve humans.
Be Human
When embarking on a technical project like a code audit, our efforts can lack context without understanding the human side. And even more importantly, our work should improve the situation for the folks who work daily within an application. As such, we should be intentional about creating a process that enables others to feel empowered, involved, and valuable.
