1.2 Basic conventions of the coding specification

Programming specifications are in no way written to increase the burden on developers and are intended to help developers write high-quality Rust code.

To accomplish this, the specification terms are divided into two categories: Principles and Rules.

• A principle is a general direction that guides programming development, or refers to a class of situations. There are also a few principles that are detectable by the Rust compiler, but because the compiler diagnostic information is confusing, principles are added to help developers avoid such situations.

• Rules, as opposed to principles, are more specific and contain positive and negative examples to further illustrate them. Some rules also add exceptions. The rules are basically detectable by lint.

Rule content Relationship with rustfmt and clippy

The specification is divided into two main parts: code style and code practice.

Code style

Code naming, formatting and comments are included in the code style.

• The naming part, mainly by clippy lint to check, some naming rules clippy lint does not provide detection, then need to custom lint to support.
• The format part, mainly using rustfmt to automatically modify, the rules in the coding specification describes most of the configuration items of rustfmt by category, in order to facilitate developers to make reference and develop their own configuration items. Configuration templates are also provided in the coding specification.
• The comments section, which includes general comments and documentation comments, rule entries are regulated through a collaboration between rustfmt and clippy.

Code Practices

The code practices are categorized by Rust language features, and each language feature is summarized as much as possible for everyday coding best practices, extracted into a list of principles and rules for developers to refer to. Most of the rules are recommendations, and the rules that are required are basically security-related.

Clippy lint involves a lot of skillful lint, so it is not put into the specification.

The rules mainly focus on generic scenarios, code readability, maintainability, security, performance of the four considerations, it only covers a small part (less than 1/5) clippy lint. There are also rules that are not available in the clippy lint and require custom lint.

The focus of the code practice content is on the Unsafe Rust coding specification, which has more coding principles than rules, and which is rarely detected by Clippy lint. There are more rules that require classes.

We hope that this section will help developers avoid some common pitfalls in writing Rust code.

Coding specification content conventions

Identified by the number before the title.

• Identified as P for Principle. Numbered as P.Element.Number.
• Identified as G for Rule (Guideline). The numbering is G.Element.Number.
• When there are subdirectories. Number is P.Element.SubElement.Number or G.Element.SubElement.Number.

Number is incremented from 01. Where Element is the three-letter abbreviation for the key element (corresponding to the secondary catalog in this specification) in the domain knowledge. (Terminology reference: SEI CERT C Coding Standard)

Reference code open source license description

All references to external code in this specification meet the MIT/Apache/Mozilla public licenses open source license!