I’ve been working on web development for seven years, working on several teams and projects, and interviewing a few developers. It turns out that the requirements for code specification vary widely from company to company, and some companies don’t even have one. Investigate its reason, nothing more than project tension, no time to sort out. Over time, as the project grew larger, maintenance became difficult, and various problems were exposed: poor code readability, bug-prone modification, chaotic logic… So teams with a little bit of technical ambition are aware of the importance of specifications.

Meaning of code specification

Start with a question: What is good code?

You may give many suggestions, such as:

  • Use fewer global variables.
  • High cohesion, low coupling.
  • Follow a single principle.
  • Have comments.
  • .

All of this is true when you think about it at the level of the individual developer. But take it a step further, from a team perspective, and consider that the developers who maintain the code are constantly changing; Add a time dimension to allow for constant code changes.

What is good code?

I once saw an author say that “consistent” code is good code, that is, all the people on the team write code as if it were written by one person. I couldn’t agree more.

Some readers might argue, is it good to write the same code? What if the team members are so low that they write bad code?

First of all, if the team members are all low performers, the code will not be “consistent”, but “different”. Back in your early days of programming, did you often search for code on the Web, assign and paste it, and then change it, only to find it worked and be OK with it? Code of this quality will differ not only in the style of code written by members, but also by a developer.

What is the meaning behind “consistent style”?

Today’s development jobs are fragmented, front end, back end, interaction designer, product manager… This is in line with the “division of labor brings efficiency” proposed by British economist Adam Smith in the Wealth of Nations, but the biggest problem it brings is the increased cost of communication (” communication “here refers to the way information is exchanged). For example, front-end communication with designers may be through PSD files, and back-end communication may be through APIS.

So there’s going to be REST API design style, there’s going to be GraphQL. In essence, they are building consensus and reducing communication costs. “Style-consistent” code specifications, like these, are designed to reduce the maintenance costs associated with writing style differences. Because although the code is running on the machine, it is still shown to people.

What are the ways to create good code specifications?

Invisible norms

Invisible norms refer to “human norms.” This is the simplest and most crude way, relying on the developer’s personal experience to guide a new hire to code, or relying on occasional code sharing and reviews. All the code specifications are in the developer’s head, and are basically passed on by language. This kind of “word of mouth” development specification, for learners because there is no documentation, all down to personal memory. Therefore, depending on personal experience and memory, different developers will have different specifications, and it is difficult to ensure that the code style is consistent.

Visible specification

Many teams use it to document various specifications. Baidu, Google a handy search “development specifications”, you can find a lot of articles. This approach solves the problem that the implementation of the specification relies on “old employees rely on experience, new employees rely on memory”, because the text is formed, which can be revised on the one hand, and can be viewed on the other hand. But documentation is just documentation, and even the best documentation can be messy. The guarantee of implementation effect has become a new problem ~

Ubiquitous norms

In this situation, code verification tools came into being. Developers can write coding specifications into configuration files, and then use the tools to verify the code. Plug-ins are also used in the development environment to prompt developers to comply with validation rules in real time. Even if a developer submits code that does not conform to the specification, there are several ways to prevent code deployment prior to deployment, such as using Git’s hook program or checking in continuous integration. This approach is very engineering-minded, and makes good use of tools to solve problems, so that the code is basically “style-consistent.” But validation tools are also limited in their ability to understand code semantics.

Ideal code specification

Since none of this is perfect, is there a better solution?

No ~ also have ~

There is no one-size-fits-all tool or method, but the good news is that we can combine them: use static validation tools to standardize the basic writing specifications of the code, then document the specifications that the validation tools can’t, and finally secure code reviews at code merge time.

For example, my specification for current front-end projects includes several forms:

  • For scripting languages TypeScript and preprocessing languages Sass, the specification documentation is omitted and the corresponding validation tools TSLint and SassLint are used. Plugins integrated with the editor can prompt developers to comply with the specification and make it easy to find questionable error messages online.
  • For more flexible parts, such as variable naming, file creation and code content, document description and code review are adopted. The review method is mutual review, where other developers review the code first and then pass it to the administrator for review.

Of course, the cost of running in this way will be slightly higher in the early stage, such as no documentation of the verification rules and time-consuming review. But as development continues, this cost tends to decrease to zero, because the more code you write, the more familiar you become with the specification, and the more times you review improvements, the more the team agrees on the code. They can also provide guidance and assistance to new team members once the code is agreed upon. From the point of view of economics, it is diminishing marginal cost and increasing income.

The last

Knowing how to avoid problems is better than knowing how to solve them, and good specifications can save you from writing bad code and a lot of time later on refactoring and fixing bugs.