From 733ac96ca64a7afeda1f895185b823805cccc2d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Joly?= Date: Tue, 15 Oct 2024 22:29:53 +0200 Subject: [PATCH] Add guidelines to format references to code elements --- docs/description.adoc | 10 ++++++++++ docs/styling_guide.adoc | 14 ++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/docs/description.adoc b/docs/description.adoc index 0b159aee48..b0da5435c9 100644 --- a/docs/description.adoc +++ b/docs/description.adoc @@ -271,6 +271,16 @@ tsql:: use `sql` In case no language is appropriate for a code block (for example shared examples between multiple languages), you can use `text` as the language. +=== References within code blocks + +When referencing a name within a comment in a code example, use double quotes to make it clear it refers to an existing element in the code. + +[source,cpp] +---- +int i = 0; +cout << noexcept(++i); // Noncompliant, "i" is not incremented +---- + === Diff view Additionally, you can also use two attributes to let the products know your code examples should be highlighted with a diff view when possible diff --git a/docs/styling_guide.adoc b/docs/styling_guide.adoc index 4b3dd42c2b..6f8e6fd522 100644 --- a/docs/styling_guide.adoc +++ b/docs/styling_guide.adoc @@ -109,3 +109,17 @@ Use it when referencing variable names, file names, tokens, and all kinds of spe Write:: Compiling source file `src/generic_file.py` breaks an `assert` call in pytest framework. Avoid:: Compiling source file "src/generic_file.py" breaks an `assert` call in `pytest` framework. +== Referencing elements from the code + +When referencing elements from the code within a normal sentence, use the `backticks` (```) to format it. This includes variable names, function names, class names, and so on. + +When referencing the same elements within a comment in a code block, surrpond it with double quotes. +[source,cpp] +---- +int i = 0; +// Write +cout << noexcept(++i); // Noncompliant, "i" is not incremented -> Double quotes +// Avoid +cout << noexcept(++i); // Noncompliant, i is not incremented -> No quotes +cout << noexcept(++i); // Noncompliant, `i` is not incremented -> Backticks +----