Today we're open-sourcing our internal Swift style guide. This is something we've been working on in an attempt to codify best practices and improve codebase consistency within the company, and it's something we'd love to have the Swift community's feedback on.
The guide is a work in progress that's intended to evolve as we undertake more and more Swift projects. We're still in the early days of Swift development, and what constitutes 'idiomatic Swift' is still in a state of flux. As both we at Bilue and the community at large decide on new best practices in Swift development, we want to keep our guide up to date with those decisions.
Why have a swift style guide?
As the number of people working on a codebase increases, you're more and more likely to encounter developers with differing opinions on how to write code. This can be about anything from tabs vs. spaces to things like when it's appropriate to use computed properties.
These differences in opinion can lead to long, drawn out debates over aesthetics during code reviews. Even once a consensus is reached, it's rarely enforced across the codebase. This approach also means the same decisions have to be made for every new project, and there's very little consistency between the projects themselves.
With a style guide, these decisions can be made once, recorded in a central repository, and then referred to by all of the projects within our company. When a debate over style comes up during a code review, developers can simply refer back to the style guide. If a developer needs to move from one project to another, they can be assured that they won't have to learn a whole host of new conventions and habits.
By codifying best practices in this way we improve consistency, reduce debate, and raise the general quality of all of our codebases.
How we built our style guide
Rather than start our guide from scratch, we've decided to fork GitHub's style guide and modify it for our own use. This has saved us a great deal of groundwork and GitHub's guide makes for a great starting point. We've made some minor changes to the original content of that guide, but so far most of our changes have been additive.
Our guide is broken up into a series of guidelines, each with a brief summary, a more detailed example to show how that pattern would be implemented, and a rationale that explains the reasoning behind that guideline. These guidelines are intended to encompass patterns that can be applied across any codebase to improve the clarity and decrease the likelihood of programmer errors.
New guidelines are added by opening a pull request on our core repo, and we generally spend some time refining new guidelines either in PR comments, or through discussion in our #swift Slack channel.
Our Swift style guide is still in its early days, but already it has sparked a lot of valuable discussion within our company. It has started pushing us towards a more consistent, company-wide coding style that makes it easier to move between projects, and is raising the baseline level of quality across each of our codebases.
If you're looking to implement a style guide at your own company, or within an open-source organisation, our guide is under a liberal Creative Commons license and we're accepting contributions.