If you search more deeply, you can find even more style guides used by tech companies or individuals. There’s not a single way to write and format code, and that’s good and healthy.
However, even with lots of conventions documented out there, many companies prefer to write their version, which usually leads to a waste of time and effectiveness, as gathering the team to discuss aesthetic aspects of the code can be both time-consuming and exhausting.
Maintaining a style guide is time-consuming
Each engineer develops a preference over time. Some people prefer tabs, others space; some prefer single quotes, others double quotes; and so on. Does the preference affect the quality of the code? I don’t think so. Does the preference affect the end-users value perception? I don’t believe it.
The fact is that quality and value aren’t expressed on coding preferences. They derive from solid processes and tools that support engineering activities. So, instead of focusing on discussing preferences, it’s more productive to focus on designing robust and well-crafted systems.
It’s fundamental to say that engineering teams and product final users benefit from a standardized codebase. The more a codebase looks like written by a single person, the faster and less buggy the development tends to be.
Community-maintained projects run this discussion with a broad reach and detach those discussions to engineering daily activities. Maintenance is more frequent and peer-reviewed than in-house solutions.
Maintaining the linter’s configuration files is laborious
Keeping a document with the company’s rules requires dedication as new versions of the programming language or framework comes out. What engineering teams always neglect is that style guides get obsolete as people leave and join the company as well.
When you hire opinionated engineers or fire senior developers in small or mid-sized teams, there are great chances that old discussions emerge again. As changing documentation is harder, linters’ configuration files differ from the predefined styles.
The same occurs with code documentation, which always ends up in the question: is it outdated documentation or an implementation bug?
Faster ramp-up of new-hires
If your company adopts a specific style guide with lots of custom rules for linters, then the ramp-up of new-hires is slower. The same may apply if different teams adopt different code conventions — which sounds against the code’s standardization. The uniqueness of the settings increases the cognitive demand for new-hires during onboarding.
It means that adopting a community-maintained style guide helps scaling companies. In fact, I strongly recommend choosing a style guide before growing fast, as the coordination efforts of doing it afterward are significantly higher.
Feedback comes from the community
I prefer a community-based solution over a custom implementation. I believe that is the best for companies I worked for and what I always foster as part of SourceLevel’s culture.
Besides all the open-source benefits, the strongest point of adopting an open-source style guide is getting external feedback. Otherwise, the team relies only on their experience. The external view brings more value to the discussion.
If the team really has strong arguments on a certain preference, the repository is open-source and will accept a pull request or issue for discussing the matter. Of course, you can’t have the change as granted. But you definitively can collaborate with the community by sharing your opinions. And this is the kind of environment I want to promote.
I think there are few exceptions to the rule. If your company is big enough or has created a framework that became very popular, you might consider creating a public style guide. The community can help in the process, and it is a win-win.
This rule applies to big open-source projects as well. After establishing the rules for that project, it can be used by other people and companies around the world. However, if you don’t intend to put effort into maintaining it, I’d adopt an existing style guide.
[wd_hustle id=”9″ type=”embedded”/]
Co-founder and CEO at SourceLevel. Co-founder at Plataformatec.
Has a Golden Retriever and a mixed-breed Pitbull.