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.
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.
Read the markup guide, the JavaScript guide and the CSS guide to understand our house style in these technologies. You should also familiarise yourself with our Git strategies. The team you're deployed to may also have its own strategies in addition to these.
We lint our CSS, JavaScript, and templates written with DustJS. This helps us to keep our different codebases consistent, avoid common logic and implementation errors, and lets us concentrate on solving problems instead of formatting.
- 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.
- For JavaScript linting, we use eslint with our own eslint configuration. You can find our principles and best practices in the JavaScript style guide.
We care a great deal about accessibility. Our target standards for all of our products are WCAG 2.1 level AA, in line with the current EU legislation, EN 301 549. All first and third party web products and components published by Springer Nature must conform to WCAG 2.1 AA.
Civil and federal legislation worldwide is converging on WCAG. Meeting WCAG 2.1 AA will also bring us into alignment with federal regulations like US Section 508 and UK Accessibility Regulations 2018, and with civil rights legislation like the UK Equality Act 2010 and the Americans with Disabilities Act.
Read our Accessibility guide to understand how we meet these aims.
We support all browsers to different degrees of functionality. "Support" does not mean that everybody gets the same thing. Read our browser support page to understand our approach and where to aim your efforts.
Our approach to 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.
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.