House style guide
This document outlines the reasons for our having a house style, and generally-applicable principles. It's a living styleguide – it will grow as our practices do.
- General Principles
- Making changes to the house style
The benefits of choosing one house style outweigh the benefits of allowing people free rein with code style. Personal preference is outweighed by the greater good. This isn't to say that we shouldn't constantly be looking to improve our ways of working. We aim to reduce friction for ourselves as we move between teams, and we do this by maintaining a general house style, linting, and agreeing on common practices.
Read this excellent article by Nicholas C. Zakas to understand why having a house style is important.
- For DustJS templates, we use Dustmite. You can find more details about how we write markup in our markup guide.
- For CSS linting, we use StyleLint and sass-lint. You can find our configuration and examples in our CSS style guide.
We care a great deal about accessibility. Our target standards for all of our products are WCAG 2.1 level AA.
All of our websites MUST comply with US Section 508 and UK Equality Act 2010. As of January 18th 2018, WCAG 2.0 AA will be incorporated into Section 508. We expect this to be updated to WCAG 2.1 AA in due course.
Read our Accessibility guide to understand how we meet these aims.
Progressive enhancement and browser support
We support all browsers to different degrees of functionality. "Support" does not mean that everybody gets the same thing. Read our graded browser support page to understand our approach and where to aim your efforts.
Using graded browser support means that you MUST practice progressive enhancement when building sites for Springer Nature, not graceful degradation. See the progressive enhancement guide to understand what this means.
We practice code review to safeguard the quality of what we produce. Code review aims to catch inadvertent mistakes, errors, and omissions (e.g. missing tests), and to act as a learning exercise for reviewers and reviewees.
Everyone is expected to review code submissions; your level of experience as a developer or with the codebase in question doesn't matter. When submitting code for review, be prepared to explain your thinking. When reviewing code, don't be afraid to ask the submitter to explain!
Read the code review guide for details on how we manage code reviews, and what to look for when reviewing.
Not all written communications need to follow house style - for e.g. we don't expect you to follow any rules in Slack, beyond what's expected of you as a professional. If you write for any of our open source repositories (including documentation), Cruft.io, or any of our social media accounts, please familiarise yourself with the Language guide. Always use inclusive language.
Making changes to the house style
The playbook outlines our current agreed house style. It's not written in stone, everybody has the opportunity to contribute and make changes. However, it's easy to waste time and effort discussing code style. We use a process to make these discussions structured and productive.
If you would like to propose a change to house style, follow these steps:
- Read the relevant page in the playbook (assuming it exists).
- Understand that you SHOULD NOT deviate from this style unless there are valid reasons in particular circumstances when the particular behaviour is acceptable or even useful.
- If you believe that your situation or case meets the criteria in point 2, detail to the rest of the team the benefits of making an exception or a change.
- If the team agrees that your exception (or change) is acceptable and useful, submit a PR to the playbook, detailing the exception (or change) to the world.