As I recently discovered, adding code quality standards to established codebases is a great way to get into tussles with other team members — and it’s for good reason. Retrofitting standards to existing code can cause a significant amount of rework. For example, imagine you are writing a large report. You finalize the outline and are 70% of the way done writing when an advisor reviews it and tells you the outline is backwards (how in the world does that happen?) and each main section needs to include subsections B and C. Depending on the scale of the report you are writing, this type of feedback could be a major effort. Code development uses the same process, and this is why it is critical to work with your team early on to determine which code quality standards you will follow and why the standards are beneficial to the team.
In this blog, I’ll cover two main areas of code quality, Code Styling and Documentation, as well as recommendations for implementing these into your organization. The following parts of this blog series will dive into development processes and code reviews.
Each coding language has a handful of recommended style guides and each developer on your team is going to have a different coding background. By adopting a style guide, your team improves code consistency both within a single codebase and across the organization’s code repositories. To enforce a style guide, there are two tools developers can leverage: beautifiers (formatters) and linters.
Comments and Documentation
As early as possible, work with your project team to determine the documentation requirements. This was an issue I faced when onboarding to a new development project and it prompted some conversation around what was acceptable documentation.
The README File
The first place a developer is going to look for information is the README file in the code repository. It seems obvious enough but I often find that README files assume too much about a user’s knowledge. At a minimum, when I look at a README file, I hope to find the following sections.
- Prerequisites – What do I need to install or set up in addition to this repository?
- Configuration – What properties or settings do I need to set before I can run the code?
- Installation – How do I install the required code dependencies?
- Run – What steps or commands should I follow to launch the application?
Each step needs to be listed out to limit the “time to action” for developers new to the codebase. As an example, let’s say that in order to run a project, the developer needs to run it as a docker container. The README does not provide instructions for how to add the project as a docker image, so the developer spends time figuring that out as they have not used docker recently or are new to docker altogether. Situations like this make the codebase harder to use and frustrating to approach. Work with your team to determine what needs to be in a README file and then, once it is made, review the file to ensure that other developers can follow it. By including more information, we can minimize the amount of extra research a developer needs to do when starting on a project.
There are a lot of debates on the web about the necessity of comments in code and I am not throwing my hat into that ring. Each language and framework tends to have its own standard for code comments and which standard you use usually comes down to personal preference. Standards ensure that we’re specifying what code does, what inputs it takes, and what outputs (or side effects) are returned as a result of the code. In some cases, standards are used to assist with documentation generation as noted in a few of the examples below.
- Python developers commonly use Google or Sphinx style comments.
- Java and PHP have standard comment formats (Javadoc and PHPDoc) that allow developers to easily generate documentation from the code.
Encourage your organization to decide what standards they want to follow given the project they’re working on. By following a standard, the developers are encouraged to document the code. Documenting code makes it more approachable and enables a developer to reflect on the code’s complexity. When a comment is hard to write or very long, perhaps the code needs to be refactored.
Code quality standards are a core component that can greatly reduce project complexity and lead to the benefits I mentioned in the previous blog. Check out the rest of the blogs in this series to find out more about development standards and the benefits they can bring to your organization.
If you have any questions or want to discuss how your organization can implement development standards into your projects, reach out to us!