From 24cc9b4026dc990b222a24b01b0a68c83a45073a Mon Sep 17 00:00:00 2001 From: dan Date: Tue, 16 Jan 2024 09:03:11 +0200 Subject: [PATCH] docs: add style guide --- CONTRIBUTING.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c75181c7a9..4147bd9727 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,4 +33,35 @@ depending on the types of changes defined by - `Fixed` for any bug fixes. - `Security` in case of vulnerabilities. -If the required subsection does not exist yet under **Unreleased**, create it! \ No newline at end of file +If the required subsection does not exist yet under **Unreleased**, create it! + +## Style + +### Capitalization and punctuation + +Both line comments and doc comments must be capitalized. Each sentence must end with a period. + +``` +// This is a line comment. +``` + +### Avoid overly long comment lines + +We recommend a soft comment line length limit of **100 characters**. Authors should aim to wrap lines before hitting this limit, but it is not a hard limit. Comments are allowed to exceed this limit. + +### Verbs in function description + +Comments describing a function usually start with a verb. That verb must use the third-person present tense, e.g. "Creates", "Sets", "Computes". + +### Function arguments + +Comments for function arguments must adhere to this pattern: + +``` +/// Performs a certain computation. Any other description of the function. +/// +/// # Arguments +/// * `arg1` - The first argument. +/// * `arg2` - The second argument. +pub fn compute(... +```