summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorStefan Metzmacher <metze@samba.org>2010-07-10 10:06:17 +0200
committerStefan Metzmacher <metze@samba.org>2010-07-10 11:18:19 +0200
commit1c2ff4563d0fd7e1d00117eef051f5554daaba14 (patch)
treed1cf7bcff3005ca137fae101271a42a18fa8349a
parent23f810041bdd990a2dfabb5fcb076a269809ce7a (diff)
downloadsamba-1c2ff4563d0fd7e1d00117eef051f5554daaba14.tar.gz
samba-1c2ff4563d0fd7e1d00117eef051f5554daaba14.tar.bz2
samba-1c2ff4563d0fd7e1d00117eef051f5554daaba14.zip
README.Coding: add examples for good and bad comments
metze
-rw-r--r--README.Coding73
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
-----------------------------------