From e2ce7f237bf06dd20620a52adacf9361aa08ad1e Mon Sep 17 00:00:00 2001 From: Jason Volk Date: Mon, 1 Jan 2018 15:23:48 -0700 Subject: [PATCH] doc: Update STYLE with commentary on comments. --- doc/STYLE.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/doc/STYLE.md b/doc/STYLE.md index 04950ba9a..cfc6c22d8 100644 --- a/doc/STYLE.md +++ b/doc/STYLE.md @@ -227,6 +227,21 @@ reseated; then the "~~big three~~" "big five" custom constructors have to be created and maintained, and it becomes an unnecessary mess. +#### Comments + +* `/* */` Multi-line comments are not normally used. We reserve this for +debugging and temporary multi-line grey-outs. The goal for rarely using this +is to not impede anybody attempting to refactor or grey-out a large swath of +code. + +* `//` Primary developer comment; used even on multiple lines. + +* `///` Documentation comment; the same style as the single line comment; the +documentation is applied to code that follows the comment block. + +* `///<` Documentation comment; this documents code preceding the comment. + + #### Miscellaneous