Initial coding guidelines published

[PLeVasseur]

Overview

Elevator pitch

Coding guidelines are available within this repository, potentially deployed to a website mdBook-style.

Detailed

In general these coding guidelines should be a set of rules of do / do not do with examples which should cover all "general" aspects of the Rust programming language, e.g. enums, structs, traits, and so on. A thought is to go over The Rust Programming Language, making a sub-issue for each chapter and section.

There should be an addendum which covers how various safety standards like ISO 26262 map onto the coding guidelines.

This serves as a tracking issue which is why it's considered "XL". Work will get logged against this in smaller chunks!

Way of work

Outline & issue breakdown

We will use the Coding Guidelines Work Items board as a means to break the work down into smaller chunks that can be tackled in a reasonable manner.

We will try to get a broad, high-level view of how we'd like to approach this work by making a skeletal outline of the coding guidelines, then open up issues as appropriate which can be worked. Frankly, it feels like a reasonable place to start is The Rust Programming Language.

@PLeVasseur will take the first attempt at this, welcome inputs!

Contribution

We are very open to receiving contributed coding guidelines in whole or in part and wholly originally contributions based on learnings from past organizational experience using Rust in safety-critical projects.

Tracking commitments and time estimates

One takeaway I had from our consortium meeting is that "something we can agree on" is better than the "currently absent" we have as the status for our coding guidelines. In that spirit I'd like to propose that we attempt to gauge both: 1. the size of individual things (and hack them down till they are "S" or so) and 2. what we can fit into workable milestones that we'll track.

As we begin working together, we'll probably be quite bad at estimating how much effort something is and see some pain points! This is totally normal and we'll adjust as we go. Take the system I'm proposing here as one an initial attempt that we'll refine.

I think in the spirit of collaboration, I'd like to see us take on the workload that each of us sees as workable to avoid over-committing, burnout, and leaving other team members hanging. Best to commit to what's achievable even if some 5-alarm thing comes up that'd pull some of your (planned) attention away.

Task Forces

Along those lines it would likely be a challenge for me to keep hold of and in my head the level of detail that will be required for the work we'll undertake. We will form a task for per piece with a directly responsible individual leading the effort.

When we take on a new piece of the language we'd like to cover we will have a directly responsible individual (DRI) that will:

• ensure that the Goals and Non-goals below are achieved
• coordinate with other task force members async on progress towards milestones
• be ambassadors as-needed to the Rust Project or other pieces of the Rust community for work items as-needed
• schedule meetings within that task force on an as-needed basis
• report out per instance we hold of the Coding Guidelines Subcommittee on progress, blockers and so on

Goals

• Coding guidelines that make a "best effort" attempt at cataloging common pieces (e.g. struct or unsafe) of the Rust programming language and how they fit into a safety-critical project
• Each piece is labeled according to a recommendation system, e.g. required, encouraged
  • Includes rationale with links to parts of the Rust Project and wider Rust community for guidance
  • Could later be refined according to various standards, e.g. DO 178 or ISO 26262
• Practical recommendations on how to use this piece of the language
  • Includes considerations of "what" is being built, e.g. broadly speaking library software: (potentially broke down further into low-level driver code, a framework system for real-time applications, SDKs) vs application software
• Should be done in parallel with addendum matrix to reduce burden of attaching these later
  • We can begin with DO 178 and ISO 26262 at perhaps chapter level, maybe subsection level for now and expand later
• Releases of the coding guidelines are tagged and released with versions of the stable compiler which they support
• Establish a set of minimal-viable sections we'd like to target with the goal of releasing something useful before we meet again in May at RustWeek

Goals obtained by discussion with Tooling Subcommittee

• Make a label for each which in theory is automateable or not
• Include for each a good and bad example of code to illustrate point
• Consider only the language reference / spec, not the tooling availability when writing the coding guidelines
• Evidence-based with statistics around human error when programming Rust to support both 1. what guidelines are written and 2. why a suggestion was made
• Produce the guidelines in an artifact that's easily machine readable and consistent format to make it easier to consume by tool vendors as a baseline (e.g. multiple JSON files, one per language piece, also potentially one large JSON concatenated together)
  • Need not be source, could be generated from a more easily human-readable format, e.g. mdBook, using some tooling

Non-goals

• For the initial version to be complete coverage of the Rust programming languages pieces
  • "Something" shipped to alleviate pressure at organizations is better than "nothing available"
• For any version to be conflict-free with various members' or their organizations' viewpoints
  • Members and their organizations may take different stances on how pieces of the Rust programming language should be viewed and approached. This is okay and expected. We'd like to ship something that we can obtain broad consensus on and worst case scenario there may be a section here or there which you may need to adjust in an internal version that'd downstream.