From Spaghetti to Lasagna: A Case for Code Consistency

Every software development team has experienced it: the exciting project, the shiny new framework, the enthusiastic client with an optimistic timeline. Left unchecked, these goals, this optimism, can prove fatal to even the best managed project. The thinking can prove disastrous for a very specific reason: code consistency. The void left by improper planning or conflicting ideas can be filled with bugs, unmaintainable fragments and every developer’s worst nightmare: spaghetti code. The argument for code consistency is a simple one, almost a no brainer: set time aside at the start of a project to define code standards and make sure the entire development team is on the same page. With a few simple tools at their disposal, a team can go from spaghetti to lasagna in no time.

Code Consistency Tools

One of the most important code consistency tools in a dev team’s toolbox is the lowly linter. A linter is a piece of software that runs through code and flags any suspicious constructs, which can be bugs, syntax errors or style inconsistencies. Most modern editors like Atom, Visual Studio Code or Intellij have plugins for linters, which are extendable and configurable to virtually any programming language. The best part about these editor-based linters is their configurability. Software teams can define code standards to their preferences, and enforce those standards to live in the editor. Early in the development process, a team should meet to hash out those code standards, either starting with a defined style guide, or from scratch and building the linter configuration to suit their needs. There are good linter options for most modern programming languages such as:

A team can jumpstart their linter configuration by utilizing a predefined style guide, like Airbnb’s Javascript Style Guide (https://github.com/airbnb/javascript), or the Angular Style Guide for Typescript (https://angular.io/guide/styleguide). Airbnb’s style guide even includes a .eslintrc configuration file to help streamline the whole process. These tools though, are useless if a preferred coding style has not been established by the team. The software team should meet, discuss personal coding styles, look over style guide, and collectively decide on a coding convention.

Documentation

Another important piece of code consistency is documentation. Incompletely or improperly documented code is a one-way street to spaghetti. Proper documentation provides clarity to developers, and eventually maintainers, on the project, and can help prevent bugs by maintaining consistency across the codebase. In the pre-development meeting, a team should decide on the documentation standard to use during development. Teams can choose from well-defined standards such as Javadoc (http://docs.oracle.com/javase/1.5.0/docs/guide/javadoc/index.html), or JSdoc for Javascript (http://usejsdoc.org/). Modern code editors can even link function calls to their function definitions, or display function help documentation based on documentation. Documentation is even pluggable into linters, ESlint, for example, has a rule that requires proper JSdoc comments on every function and class. With proper documentation, a code base can become layered, and as easily read as lasagna.

Source Control

The third, and simplest, tool in a dev team’s toolbox is proper utilization of source control. No matter the chosen SCM (Source Control Manager), a commit standard should be established. Commits should be compact, they should only include changes from related edits, they should be categorized, file creations and deletions should be committed separately from edits, and they should be organized, feature branches are a dev team’s best friend. Likewise, commit messages should be short, succinct and to the point, providing descriptive information about the changes made. If the team uses team collaboration software such as JIRA, Trello or Github, commit messages should be tagged with issue numbers to link to feature descriptions and bug reports. With proper source control management, a team’s collaboration can rocket to new heights of productivity.

When planning a new software development project, be sure to plan for code consistency. A strong code base can transform a messy project into a streamlined, efficient productivity powerhouse, empowering developers and providing clarity and insight to project managers and product owners.