engineering

Ably Engineering Team: Coding Standards

Our preference at Ably is not to publish and attempt to keep maintained code standard documents that are designed to be purely human readable. The modern approach to conforming code formatting is to use linters and the modern approach to spotting structural issues is to use static analysis.

The purpose of this document is:

• To provide meta-documentation (very high level) around what we’re doing, and where, in respect of linting and static analysis.
• To provide a canonical point of reference for rules that either cannot be applied using linting or static analysis, or which we would like to use linting or static analysis for in future. This should not be a massive list.

Linting and Static Analysis

We should always aim to use the validating tools which are idiomatic for the language and platform that developers are working with.

Those tools should be run in CI and those checks passing must be a requirement for pull requests to be merged.

Other Rules

Boilerplate Content and Individual Attribution

Remove comment headers and unused boilerplate wherever possible before committing files.

This includes headers where your own name is included - the worst offender being Xcode’s default template file layouts. See this review comment for an example.

Repository Components

This page documents the layout to which our open source client library repositories should conform. It must be applied to new repositories before they are opened up to public visibility. It should be applied to existing repositories that don’t already confirm as a matter of priority.

The following files must always be present in the root folder:

• COPYRIGHT: Single line. Plain text. Example.
• LICENSE: Unmodified Apache-2.0. Plain text. Example.
• MAINTAINERS.md: Single line. Plain text, encapsulated as markdown. Example.
• README.md: Template.
• CONTRIBUTING.md: Template.
• CHANGELOG.md: Must be present from the second release onwards. The contents is intended to be human readable so style can vary between libraries, however we broadly follow the format generated by the ubiquitous github-changelog-generator tool. Example.

The following files might be present in the root folder:

• .editorconfig: Guidance for IDEs around formatting of source code files.
• .gitignore: Rules for Git clients to prevent accidental checkin of transitory files. Guidance on what should and shouldn’t be included is in our Git Standards and Best Practices.

Where possible we should avoid having too many files or folders at repository root level, purely for the practical aspect that this affects the “above the fold” viewing experience in GitHub’s UI for the repository home page.

This site is open source. Improve this page.