From 464ea4c0ac1318287bcf3985efeae34c3ed8b521 Mon Sep 17 00:00:00 2001 From: Stefan Metzmacher Date: Sat, 10 Jul 2010 10:06:17 +0200 Subject: [PATCH] README.Coding: add examples for good and bad comments metze --- README.Coding | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 72 insertions(+), 1 deletion(-) diff --git a/README.Coding b/README.Coding index ba70a3c53129..b1ac2fe6666c 100644 --- a/README.Coding +++ b/README.Coding @@ -94,8 +94,79 @@ Comments -------- Comments should always use the standard C syntax. C++ -style comments are not currently allowed. +style comments are not currently allowed. The lines before +a comment should be empty. If the comment directly belongs +to the following code, there should be no empty line after +the comment. In case the comment contains a summary of +mutliple following code blogs. +This is good: + + ... + int i; + + /* + * This is a multi line comment, + * which explains the logical steps we have to do: + * + * 1. We need to set i=5, because... + * 2. We need to call complex_fn1 + */ + + /* This is a one line comment about i = 5. */ + i = 5; + + /* + * This is a multi line comment, + * explaining the call to complex_fn1() + */ + ret = complex_fn1(); + if (ret != 0) { + ... + + /** + * @brief This is a doxygen comment. + * + * This is a more detailed explanation of + * this simple function. + * + * @param[in] param1 The parameter value of the function. + * + * @param[out] result1 The result value of the function. + * + * @return 0 on success and -1 on error. + */ + int example(int param1, int *result1); + +This is bad: + + ... + int i; + /* + * This is a multi line comment, + * which explains the logical steps we have to do: + * + * 1. We need to set i=5, because... + * 2. We need to call complex_fn1 + */ + /* This is a one line comment about i = 5. */ + i = 5; + /* + * This is a multi line comment, + * explaining the call to complex_fn1() + */ + ret = complex_fn1(); + if (ret != 0) { + ... + + /*This is a one line comment.*/ + + /* This is a multi line comment, + with some more words...*/ + + /* + * This is a multi line comment, + * with some more words...*/ Indention & Whitespace & 80 columns ----------------------------------- -- 2.34.1