Engineering Guidelines are a collection of Best Practices for your organization;a condensed version of institutional wisdom regarding “how things should be done here.”They are a combination of an Engineering Department Employee Handbook, Company Values, and Mission Statement.

Does your company have engineering guidelines? It should

You must establish the following standards: the code (its style, formatting, and tests); the procedure for development (CI, code review, and deployments); and the service (logging, flags, configuration, metrics).

The “cultural” guidelines for your engineering department should also be written down, but for the time being, they will be ignored.On the design side, user-visible aspects will also require consistent UI and UX. ((Those are beyond the scope of this article.)

More things work as expected with fewer surprises

At smaller organizations, guidelines manage the freedom from less corporate inertia around how to do things. This freedom can easily lead to a much larger variety of practices which can be difficult to rein in later.

Your guidelines don’t exist in isolation. They frequently need institutional support to be effective. For example, if the guidelines state the recommended way to set up automated CI builds requires multiple commits to different repositories with different teams needing to +1 the changes *and* multiple coordinated rollouts, then few projects are going to bother to properly set up CI for their projects. You need to make it easy to do the right thing.

The Code

When most people think of guidelines, they usually think of these:a document that specifies four-space indents, braces in the Allman style, and a 10-line Javadoc listing the inputs and outputs for each function. the organization will also benefit from having existing guides documented and/or linked to them.

The following is a summary from Rob Pike’s “Go Proverbs”: Even though, no one likes his style. The consistency of the style is more important than the exact style. Additionally, if choosing a style is difficult, it indicates that both options are acceptable and that a coin flip is required.

The Development Process.

The process of writing code in an editor and successfully merging it into HEAD is just one of many steps involved in modern software development. For each of them, this section will have policies in place.

Here are some suggestions:

CI compiler flags (optimization levels, debug info, warnings) and expectations for tests, including coverage and policies for unit, integration, and end-to-end tests, are set up in the commit message format.

which static analysis software to use, when, and how to use code generation software. branch usage and naming squash/merge and multi-commits versus rebase/force-push during code review iterations. issue trackers require size estimates (S/M/L/XL), bug priorities, and workflow documentation for deployments: staging, canaries, incremental deployments, rollbacks, and documents outlining incident handling and post-mortems all cover vocabulary and definitions to ensure that everyone understands each other.

The Service

How does your service communicate with other services once it is operational? Is it necessary to speak with a directory service? What about authentication for services? Is it speaking JSON or something else over HTTP(S)? What should be the retry plan? How does it deal with versioning APIs?Each of these questions must be answered for the service to function as both a client and a server.

Last but not least, how do you convey the events to the rest of the world? What are the minimum policies regarding metrics and logging?For logs, what ought to be logged, and where does it go? Do the records have a free-form structure? What are the naming guidelines for standard fields when using structured logs? Do you have various levels of logging verbosity? If this is the case, what are they, and what should be recorded at each level? Again, metrics require a unified location and consistent guidelines for what to track and how to name them. How is the collection of distributed traces done?

This section can also list banned and recommended libraries for various tasks, each with its justification section.

Writing Your Own Guidelines

I spent a lot of time looking for best practices from organizations that were similar to mine, with justifications if possible, to see if their objectives were identical to mine. For instance, individuals frequently try to imitate Google’s engineering practices and apply them to their own organizations by pointing to them. However, many practices that make sense at Google do not apply to other businesses. You can’t just wholly absorb the policies of another company without making assumptions about its culture and infrastructure. This may be further explored in a subsequent blog post, which I’ve tentatively titled “The parable of Blog.”)