Skip to content

Latest commit

 

History

History
89 lines (60 loc) · 2.69 KB

STYLE.md

File metadata and controls

89 lines (60 loc) · 2.69 KB
Raw

Secretless Broker Style Guide

Use this guide to maintain consistent style across the Secretless Broker project.

Generally, when you are contributing code changes to this project you should leverage golint as you work to get suggestions for style fixes you should make.

To use golint on any project path, run

go install golang.org/x/lint/golint@latest
golint ./[path]/...

Other general guidelines

Be consistent

If you’re editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too.

The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you’re saying rather than on how you’re saying it. We present global style rules here so people know the vocabulary, but local style is also important. If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Avoid this.

Prose

Secretless Broker prose should be warm, direct, and clear about its intended audience. When editing copy, follow the Chicago Manual of Style.

Documentation

Documentation is written to be familiar with the reader. Use you & your to refer to the reader, we us & our to refer to the contributors.

When giving examples, use a generic example that the reader can relate to. For example: a website connecting to a database.

Give names to machines according to their function, eg database-server. Give names to humans using the alphabetical convention common in cryptography research.

Tests

When writing tests, treat your descriptions as prose to be read and understood by humans.

Code

Secretless Broker code favors readability over cleverness.

Continuous integration

Consider the guidelines in The Ten-Factor CI Job.

Contributing

If this guide is lacking, please feel free to open a pull request to include additional guidelines.

Good guideline are:

  • Distinctive

    The reader can tell which part of the guide covers the project they're working on.

  • Definitive

    The readers can distinguish whether their work follows the guidelines or not.

  • Actionable

    The reader has clear guidance on how to improve content that doesn't follow the style.