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.
Code Styling
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.
Beautifiers
Beautifiers make code look, you guessed it, beautiful. These tools focus on improving code quality by enforcing readability standards and making the code look the same regardless of who wrote it. Common formatting rules enforced by a beautifier are max line length, comma spacing, and the usage of language keywords (If-else, switch-case, etc.). I recently started using two “opinionated” formatters, Prettier for Javascript and Black for Python, and I appreciate the consistency they enforce. The standard formatting makes it easier for developers to onboard to a codebase and add their own code. Beautifiers provide consistent code styles and enable developers to focus on the problems they are trying to solve without needing to worry about the details of formatting.
Linters
Linters focus on catching bugs, security issues, and identifying optimization points. While beautifiers focus on how a code looks, linters are more likely to recommend refactoring code as they point out when functions are too long or a single file contains too much functionality. This prompts developers to write cleaner code and refactor individual components into separate functions or files. Additionally, linters surface security and optimization issues that ensure the team is writing both secure and efficient code. Linters are the equivalent of the advisor in the previous example–they recommend changes and point out known issues based on a list of rules. However, it is up to each team to decide what rules they want to follow. I currently recommend ESLint for Javascript and Pylint for Python as they are easy to get set up and provide great recommendations.
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.
Comment Standards
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.
- Javascript implements a similar format, JSDoc, that is great for some codebases but not all.
- When writing in React, a Javascript framework, the common standard is to not include comments at all since the code itself is very componentized and should be easy to follow.
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.
Conclusion
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!