DevTools/CodingStandards: Difference between revisions

DevTools/CodingStandards (view source)

Revision as of 14:53, 7 March 2016

1,212 bytes added , 7 March 2016

Added guidelines about comments

Pbrosset

130

edits

@@ Line 109: / Line 109: @@
 * use Maps, Sets, WeakMaps when possible,
 * use [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals <code>`template strings`</code>] whenever possible to avoid concatenation, allow multi-line strings, and interpolation
+== Comments ==
+Commenting code is important, but bad comments can hurt too, so it's important to have a few rules in mind when commenting:
+* If the code can be rewritten to be made more readable, then that should be preferred over writing an explanation as a comment.
+* Instead of writing a comment to explain the meaning of a poorly chosen variable name, then rename that variable.
+* Avoid long separator comments like <code>// ****************** another section below **********</code>. They are often a sign that you should split a file in multiple files.
+* Line comments go above the code they are commenting, not at the end of the line.
+* Sentences in comments start with a capital letter and end with a period.
+* Watch out for typos.
+* Obsolete copy/pasted code hurts, make sure you update comments inside copy/pasted code blocks.
+* A global comment at the very top of a file explaining what the file is about and the major types/classes/functions it contains is a good idea for quickly browsing code.
+* If you are forced to employ some kind of hack in your code, and there's no way around it, then add a comment that explains the hack and why it is needed. The reviewer is going to ask for one anyway.
 == Advice to patch authors ==