--- a/doc/v2_planning/coding_style.txt	Thu Oct 07 16:42:12 2010 -0400
+++ b/doc/v2_planning/coding_style.txt	Thu Oct 07 16:49:04 2010 -0400
@@ -405,26 +405,32 @@
       https://theanoclone.googlecode.com/hg/". It is too long to ask people to
       use the same. I guess "Merge" would be the most logical message to use.
 
-FB: The proposed guide line
-    * A one line summary
-    * If needed a blanc line followed by a more detailed summary
+FB: The proposed guidelines
+    * A one line summary. Try to keep it short, and provide the information
+      that seems most useful to other developers: in particular the goal of
+      a change is more useful than its description (which is always
+      available through the changeset patch log). E.g. say "Improved stability
+      of cost computation" rather than "Replaced log(exp(a) + exp(b)) by
+      a * log(1 + exp(b -a)) in cost computation".
+    * If needed a blank line followed by a more detailed summary
     * Make a commit for each logical modification
-        * This make review easier to do
-        * This make debugging easier as we can more easily pinpint error in commit with hg bisect
-    * NEVER commit reformating change with functionality
+        * This makes reviews easier to do
+        * This makes debugging easier as we can more easily pinpoint errors in commits with hg bisect
+    * NEVER commit reformatting with functionality changes
     * HG RECORD/DIFF are your friend
-        * hg record allow you to record select the change to a file to commit
-        * hg record force you to review your code!
-    * Review your code before commit
+        * hg record allows you to select which changes to a file should be
+          committed
+        * hg record / diff force you to review your code, never commit without
+          running one of these two commands first
     * Stuff from django guide
         * Write detailed commit messages in the past tense, not present tense.
             * Good: "Fixed Unicode bug in RSS API."
             * Bad: "Fixes Unicode bug in RSS API."
             * Bad: "Fixing Unicode bug in RSS API."
         * Separate bug fixes from feature changes.
-        * ? If fix a ticket, make the message start with "Fixed #abc"
+        * If fix a ticket, make the message start with "Fixed #abc"
             * Can make a system to change the ticket?
-        * ? If reference a ticket, make the message start with "Refs #abc"
+        * If reference a ticket, make the message start with "Refs #abc"
             * Can make a system to put a comment to the ticket?