Communication in Code: Engineering Standards for Growing Teams
We care a lot about quality at Prolific. From how a product looks to how it works and feels, everything is looked after with attention. For that reason, we created a set of internal processes, conventions, and best practices for developing apps that work, are maintainable, and whose codebase can be handed over to our partners with pride. While it may seem simple, maintaining quality across a variety of projects with different engineers is a challenge.
Our main objectives for creating and maintaining high-quality apps are:
- Writing code that is clean and easy to maintain.
- Minimizing onboarding for any developer who jumps in at any time.
- Identifying and automating repetitive tasks.
- Improving our process and code quality over time.
How can we achieve all of that simultaneously? Well, we have a few recipes that have worked well for us and hopefully can help you.
The Prolific Cookbook
1. Standardize your code conventions and style
Creating a set of shared rules makes every project feel like home, for both the developer who has been working on it since day one and the developer who joined the effort in the last few weeks prior to release.
These rules cover:
- Project setup and file organization
- Coding conventions and formatting rules
- Common libraries used across all projects
- Shared scripts and tools (for debugging, building, distributing, sending feedback, etc.)
Taking the time to set up these rules and to reach a consensus pays off. Whether the team is building a single product, a suite of tools, or a new app every few months, there is always room for best practices. These help teammates work seamlessly together, and anyone who jumps in later will be able to understand what’s going on without too much effort.
2. Enforce your standards
Code reviews should be enforced for every single line of code. They help the team get better in many ways:
- They allow reviewers to see how their teammate tackled a given problem in ways they wouldn’t have initially thought of. For instance it facilitates experienced engineers to share their wisdom with more junior developers.
- They facilitate communication between teammates and help a lot with the overall process by creating material for future conventions.
- They keep everybody on the same page regarding best practices and standards, from within a product team to the entire engineering department.
- They help enforce standards and keep everybody honest with each other.
Quick note, it is also imperative to use a distributed version control system. Though it is probably a given these days, it is still worth stressing its importance in a development team’s daily workflow. The most popular one by far is Git, and it is great for so many reasons.
A good way to check that everybody is following a set of standards is to set up an audit system. Ours is simple yet efficient: we put together a spreadsheet of checkpoints for our quality standards and organized them into sections. That’s it — the audit was ready to go!
At Prolific, every project is audited once a month. The auditors are usually team leads; they work on their own product and review someone else’s codebase. In order to track progress, every item is graded and has a weight. An overall grade is computed from those values and is saved in a master spreadsheet.
Our typical audit cycle happens in three phases:
- The auditor checks out the current development branch and checks a list of items organized into sections, such as code conventions, documentation, compiler, security, tools, Git, continuous integration, open-source, or tests coverage.
- Once the audit is complete, the auditor and auditee meet and go through a list of comments in order to determine action items together. These can be about the project (how to improve to meet standards, fix relevant issues, add missing required elements, etc.) or the audit process itself (refine rules based off new scenarios, add new items that just came up, or remove rules that are no longer relevant or not applicable). Previous items are checked. New items are created.
- Action items are addressed: the project technical quality increases and the audit process is refined and directly benefits other teams. After a month, the cycle starts over, previous action items are reviewed, and the latest codebase is checked to make sure that standards are being maintained.
Overall, both code reviews and audits have proven efficient and an invaluable part of our process for assuring consistent quality.
Once engineering conventions are set up, it’s important to ensure everyone is aware of them. And let’s face it, that is not an easy task, especially as the team grows. Sending an email or a quick message on Slack every time something new happens is an option, but the update can often fall through the cracks. So how do we make sure everybody is on the same page?
When it comes to talking about a specific subject, I previously mentioned code reviews and audits which, along with other educational opportunities, are key components of communication within and between teams. They facilitate very specific conversations that would hardly happen otherwise and help to uncover issues in the development process. Teammates look after each other while maintaining and improving conventions and best practices.
Finally, the best tool for communicating updates for us came out to be an internal blog just for the engineering team. This blog provides a platform to update each other on anything: the process, the latest add-on in the best practices section, resources for the presentation that just happened (e.g. a technical post-mortem), shared references, or anything else relevant to the team. It’s very easy to set up and also incredibly efficient for passing on information. And when there is a need to elaborate on a specific topic, dev talks are the perfect avenue.
4. Make documentation a priority
Documentation is no one’s favorite topic, but its utility cannot be overstated. Having everyone on the team document at least public methods and properties with descriptive comment blocks will save precious time in the long run. It’s very important to do so because it helps new team members (or our future selves!) quickly understand APIs without having to read through entire implementations. Using descriptive names and keeping methods short is also very beneficial.
At Prolific, we also focus on writing a very comprehensive README by making sure that it details high-level architecture decisions, complex components or anything out of the ordinary. We try to encourage our engineers to think to themselves:
Imagine your future self jumping into the code in a year: will you understand what’s going on? How would you like it to be explained to you?
Keeping the README up to date over time is important. If something gets updated, refactored, or simply is deleted, we update the documentation accordingly and review it in the aforementioned audits.
Depending on the complexity of the code and architecture, our engineers may also create diagrams and other charts explaining how things work. Often a picture is worth a thousand words and mixing up graphical representations of ideas with text can be very beneficial.
5. Write tools to help streamline the process
When there is a spare hour, we work on more tools and scripts that make sense for the rest of the team to use. Scripts can help make the continuous deployment and integration process a breeze. For instance, ours automate the following tasks:
- Creating and distributing a build
- Bumping version and build numbers
- Generating changelogs
- Pushing to the App Store or Google Play Store
- Running the test suite for every build (or even every pull request)
- Generating and publishing documentation
- Facilitating the translation process
- Generating a brand new project and all its base scripts from scratch, including automatically setting up third party services
These are just some examples of scripts that can save any development team a tremendous amount of time. All that precious time can now be used for writing more tests, improving those tools, or making your app look and feel even more unique. It is important to note that there are a considerable amount of open source tools out there. There’s no need to spend valuable time unnecessarily reinventing the wheel! Research what you want to do first; most of the time, you will find what you are looking for.
No one’s process is perfect, and yours won’t instantly be perfect if you choose to go down this path. You’ll need to constantly check on it and work on improving it. Ours has already produced very beneficial results:
- It puts the entire team in the same mindset.
- It helps code readability across the board.
- It helps make code reviews more streamlined and effective.
- It helps speed up project setup thanks to scripts and templates.
- It allows the team to focus on other things, such as improving its tools.
Important note: there needs to be flexibility in the process. Even if something works, it should never be made sacred. There is no reason things can’t change in the future. If someone has an idea for improvement, it’s probably worth listening to and maybe giving it a shot. You never know!
On top of those benefits, the Prolific Cookbook allows us to create stronger codebases faster, satisfying our passion for high quality and allowing us to spend time on the polished experience that makes our end users happier. And now that you know the recipe, your next five-star app is on its way!