diff doc/v2_planning/coding_style.txt @ 1070:79eb0016f333

coding_style: Added a couple points to debate
author Olivier Delalleau <delallea@iro>
date Fri, 10 Sep 2010 10:28:51 -0400
parents 4f287324a5ad
children 04bbf05d249c 3e7978201ffc
line wrap: on
line diff
--- a/doc/v2_planning/coding_style.txt	Fri Sep 10 10:28:34 2010 -0400
+++ b/doc/v2_planning/coding_style.txt	Fri Sep 10 10:28:51 2010 -0400
@@ -198,3 +198,14 @@
     key in my_dict              my_dict.has_key(key)
     sub_string in my_string     my_string.find(sub_string) >= 0
 
+    * (Point to debate) Avoid contractions in code comments (particularly in
+      documentation): "We do not add blue to red because it does not look
+      good" rather than "We don't add blue to red because it doesn't look
+      good". I mostly find it to be cleaner (been used to it while writing
+      scientific articles too).
+
+   * (Point to debate) Imperative vs. third-person comments. I am used to the
+     imperative form and like it better only because it typically saves one
+     letter (the 's'): "Return the sum of elements in x" rather than
+     "Returns the sum of elements in x".
+