Stand on the shoulders of style-guide genius

TL;DR; Adopt popular or canonical engineering guidelines and stick to them; avoid creating in-house engineering guides; avoid changing the existing guidelines that the team adopts.

In other words, avoid not-invented-here syndrome (NIH syndrome) for software development process.

NIH syndrome is the predilection to reinvent-the-wheel because "it was not invented here." It is often associated with algorithms, frameworks, and libraries, in which case a development team creates its own Math library, even though System.Math already exists. NIH syndrome also applies to softer aspects of engineering such as style guidelines, scrum processes, and version control flows.

A common time trap is the in-house style guide. Having a style guide is very important for development velocity. Among other benefits, adhering to a style-guide improves code readability and reduces software bugs. That said, inventing a new, in-house style guide is not important and can have significant down side, such as decreased moral, in-fighting, and a muddled half-effort. Solution: use an existing style guide (or as Rick suggests: automate code formatting to the extent possible).

Aside: The usual path of an in-houes style guide: Developers debate things like line length or tabs versus spaces. Once developers reach a decision, someone adds the guideline to a curated, in-house style guide. That in-house style guide tends toward disuse and quickly becomes out-of-date and/or lacks more than 10 guidelines. Developers give up on its maintenance and stop reading it. Since the guidelines were made in-house and went to the person with the loudest, most persistent voice, the guidelines are misguided and change to often.

It is much more effective to use a canonical style-guide for the language your team uses. For ECMAScript, use the AirBnb style guide. For C#, use the ASP.NET team's style guide or automate with StyleCop. If there is no single canonical style-guide, choose a really popular one.

"How we do development at Our Medium-Sized Business" should look similar to this:

No more arguments. Just productivity and some additional benefits:

  • It's easier to on-board new developers when we use canonical processes.
  • Efficiency increases as we implement hard earned practices from industry.
  • Learning occurs as we understand nuanced process edge cases.

When the team chooses a style guide or a version control flow, endeavor to stick to it without exceptions. See it as sacrosanct holy law. If the team does want to make a change, make an official change request to the third-party guide. That will avoid time wasting debates.

Industries other than software development have guidelines in professional colleges or laws. Law abiding construction in British Columbia must be built "to code." Maybe someday software development will have a similar legal enforcement.

The same ideas as above apply to version control flows. Git is popular these days, and there are about a dozen (citation needed) branching and merging models. Choose one! Do not come up with a new one (unless that is a product that your stakeholders are wanting to sell.) Use GitFlow, use GitHub Flow, or use another popular flow that has become one of the de factor industry standards.