2011-02-26 David Levin <levin@chromium.org>
authorlevin@chromium.org <levin@chromium.org@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Sat, 26 Feb 2011 14:45:10 +0000 (14:45 +0000)
committerlevin@chromium.org <levin@chromium.org@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Sat, 26 Feb 2011 14:45:10 +0000 (14:45 +0000)
        Reviewed by Darin Adler.

        Add style guidelines about comments from the unwritten rules email.
        https://bugs.webkit.org/show_bug.cgi?id=55272

        * coding/coding-style.html: Added the guidelines.

git-svn-id: https://svn.webkit.org/repository/webkit/trunk@79785 268f45cc-cd09-0410-ab3c-d52691b4dbfc

Websites/webkit.org/ChangeLog
Websites/webkit.org/coding/coding-style.html

index c5de14b..6f0d176 100644 (file)
@@ -1,3 +1,12 @@
+2011-02-26  David Levin  <levin@chromium.org>
+
+        Reviewed by Darin Adler.
+
+        Add style guidelines about comments from the unwritten rules email.
+        https://bugs.webkit.org/show_bug.cgi?id=55272
+
+        * coding/coding-style.html: Added the guidelines.
+
 2011-02-09  Alexander Pavlov  <apavlov@chromium.org>
 
         Unreviewed. Add Web Inspector stylesheet resource diff screenshot.
index 9bcf019..aab6d57 100644 (file)
@@ -971,6 +971,42 @@ public:
 </li>
 </ol>
 
+<h3>Comments</h3>
+<ol>
+<li>Use only <i>one</i> space before end of line comments and in between sentences in comments.
+<h4 class="right">Right:</h4>
+<pre class="code">
+f(a, b); // This explains why the function call was done. This is another sentence.
+</pre>
+
+<h4 class="wrong">Wrong:</h4>
+<pre class="code">
+int i;    // This is a comment with several spaces before it, which is a non-conforming style.
+double f; // This is another comment.  There are two spaces before this sentence which is a non-conforming style.
+</pre>
+</li>
+
+<li>
+Make comments look like sentences by starting with a capital letter and ending with a period (punctation). One exception may be end of line comments like this "if (x == y) // false for NaN".
+</li>
+
+<li>
+Use FIXME: (without attribution) to denote items that need to be addressed in the future.
+</li>
+<h4 class="right">Right:</h4>
+<pre class="code">
+drawJpg(); // FIXME: Make this code handle jpg in addition to the png support.
+</pre>
+
+<h4 class="wrong">Wrong:</h4>
+<pre class="code">
+drawJpg(); // FIXME(joe): Make this code handle jpg in addition to the png support.
+</pre>
+<pre class="code">
+drawJpg(); // TODO: Make this code handle jpg in addition to the png support.
+</pre>
+</ol>
+
 <?php
     include("../footer.inc");
 ?>