diff options
| author | Stefan Metzmacher <metze@samba.org> | 2010-07-10 10:06:17 +0200 |
|---|---|---|
| committer | Stefan Metzmacher <metze@samba.org> | 2010-07-10 11:18:19 +0200 |
| commit | 1c2ff4563d0fd7e1d00117eef051f5554daaba14 (patch) | |
| tree | d1cf7bcff3005ca137fae101271a42a18fa8349a | |
| parent | 23f810041bdd990a2dfabb5fcb076a269809ce7a (diff) | |
| download | samba-1c2ff4563d0fd7e1d00117eef051f5554daaba14.tar.gz samba-1c2ff4563d0fd7e1d00117eef051f5554daaba14.tar.bz2 samba-1c2ff4563d0fd7e1d00117eef051f5554daaba14.zip | |
README.Coding: add examples for good and bad comments
metze
| -rw-r--r-- | README.Coding | 73 |
1 files changed, 72 insertions, 1 deletions
diff --git a/README.Coding b/README.Coding index ba70a3c531..b1ac2fe666 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 ----------------------------------- |