StarMirror/styleguide
1
0
Fork 0
mirror of https://github.com/google/styleguide.git synced 2024-03-22 13:11:43 +08:00
Code Issues Projects Releases Wiki Activity

Update C++ style guide to 3.174:

Browse Source 
- Add leading blank line exception.
 - Improve guidance for function definition comments.
 - Tweak class comment example to not violate type naming guidelines.

Update Objective-C style guide to 2.21:
 - Prohibit +new.

Update JavaScript style guide to 2.9:
 - Add new "Function Declarations Within Blocks" section.
 - Add new "Internet Explorer's Conditional Comments" section.
 - Add new "Alias long type names to improve readability" section.
 - Add @lends.
This commit is contained in:
mmentovai 2010-10-04 16:26:53 +00:00
parent b729e3cfe3
commit 7ead64485b
3 changed files with 169 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
cppguide.xml
View File

@ -4,7 +4,7 @@
<p align="right"> <p align="right">
Revision 3.171 Revision 3.174
</p> </p>
@ -3151,12 +3151,12 @@ Tashana Landray
<BODY> <BODY>
<CODE_SNIPPET> <CODE_SNIPPET>
// Iterates over the contents of a GargantuanTable. Sample usage: // Iterates over the contents of a GargantuanTable. Sample usage:
// GargantuanTable_Iterator* iter = table-&gt;NewIterator(); // GargantuanTableIterator* iter = table-&gt;NewIterator();
// for (iter-&gt;Seek("foo"); !iter-&gt;done(); iter-&gt;Next()) { // for (iter-&gt;Seek("foo"); !iter-&gt;done(); iter-&gt;Next()) {
// process(iter-&gt;key(), iter-&gt;value()); // process(iter-&gt;key(), iter-&gt;value());
// } // }
// delete iter; // delete iter;
class GargantuanTable_Iterator { class GargantuanTableIterator {
... ...
}; };
</CODE_SNIPPET> </CODE_SNIPPET>
@ -3260,7 +3260,7 @@ Tashana Landray
<SUBSECTION title="Function Definitions"> <SUBSECTION title="Function Definitions">
<p> <p>
Each function definition should have a comment describing Each function definition should have a comment describing
what the function does and anything tricky about how it does what the function does if there's anything tricky about how it does
its job. For example, in the definition comment you might its job. For example, in the definition comment you might
describe any coding tricks you use, give an overview of the describe any coding tricks you use, give an overview of the
steps you go through, or explain why you chose to implement steps you go through, or explain why you chose to implement
@ -4356,9 +4356,10 @@ Tashana Landray
<p> <p>
This is more a principle than a rule: don't use blank lines This is more a principle than a rule: don't use blank lines
when you don't have to. In particular, don't put more than when you don't have to. In particular, don't put more than
one or two blank lines between functions, don't start or end one or two blank lines between functions, resist starting
functions with a blank line, and be discriminating with your functions with a blank line, don't end functions with a blank
use of blank lines inside functions. line, and be discriminating with your use of blank lines
inside functions.
</p> </p>
<p> <p>
The basic principle is: The more code that fits on one screen, The basic principle is: The more code that fits on one screen,
@ -4369,39 +4370,16 @@ Tashana Landray
whitespace. whitespace.
</p> </p>
<p> <p>
Don't start or end functions with blank lines: Some rules of thumb to help when blank lines may be useful:
<BAD_CODE_SNIPPET>
void Function() {
// Unnecessary blank lines before and after
}
</BAD_CODE_SNIPPET>
</p>
<p>
Don't start and end blocks with blank lines either:
<BAD_CODE_SNIPPET>
while (condition) {
// Unnecessary blank line after
}
if (condition) {
// Unnecessary blank line before
}
</BAD_CODE_SNIPPET>
However, it's okay to add blank lines between a chain of
if-else blocks:
<CODE_SNIPPET>
if (condition) {
// Some lines of code too small to move to another function,
// followed by a blank line.
} else {
// Another block of code
}
</CODE_SNIPPET>
</p> </p>
<ul>
<li> Blank lines at the beginning or end of a function very
rarely help readability.
</li>
<li> Blank lines inside a chain of if-else blocks may well
help readability.
</li>
</ul>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
</CATEGORY> </CATEGORY>
@ -4551,7 +4529,7 @@ Tashana Landray
<HR/> <HR/>
<p align="right"> <p align="right">
Revision 3.171 Revision 3.174
</p> </p>

136
javascriptguide.xml
View File

@ -3,7 +3,7 @@
<GUIDE title="Google JavaScript Style Guide"> <GUIDE title="Google JavaScript Style Guide">
<p class="revision"> <p class="revision">
Revision 2.3 Revision 2.9
</p> </p>
<address> <address>
@ -173,6 +173,32 @@
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Function Declarations Within Blocks">
<SUMMARY>No</SUMMARY>
<BODY>
<p>Do not do this:</p>
<BAD_CODE_SNIPPET>
if (x) {
function foo() {}
}
</BAD_CODE_SNIPPET>
<p>While most script engines support Function Declarations within blocks
it is not part of ECMAScript (see
<a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMA-262</a>,
clause 13 and 14). Worse implementations are inconsistent with each
other and with future EcmaScript proposals. ECMAScript only allows for
Function Declarations in the root statement list of a script or
function. Instead use a variable initialized with a Function
Expression to define a function within a block:</p>
<CODE_SNIPPET>
if (x) {
var foo = function() {}
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Exceptions"> <STYLEPOINT title="Exceptions">
<SUMMARY>Yes</SUMMARY> <SUMMARY>Yes</SUMMARY>
<BODY> <BODY>
@ -548,6 +574,20 @@
avoided.</p> avoided.</p>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Internet Explorer's Conditional Comments">
<SUMMARY>No</SUMMARY>
<BODY>
<p>Don't do this:</p>
<CODE_SNIPPET>
var f = function () {
/*@cc_on if (@_jscript) { return 2* @*/ 3; /*@ } @*/
};
</CODE_SNIPPET>
<p>Conditional Comments hinder automated tools as they can vary the
JavaScript syntax tree at runtime.</p>
</BODY>
</STYLEPOINT>
</CATEGORY> </CATEGORY>
<CATEGORY title="JavaScript Style Rules"> <CATEGORY title="JavaScript Style Rules">
@ -683,6 +723,65 @@
</SUBSUBSECTION> </SUBSUBSECTION>
<SUBSUBSECTION title="Alias long type names to improve readability">
<p>Use local aliases for fully-qualified types if doing so improves
readability. The name of a local alias should match the last part
of the type.</p>
<CODE_SNIPPET>
/**
* @constructor
*/
some.long.namespace.MyClass = function() {
};
/**
* @param {some.long.namespace.MyClass} a
*/
some.long.namespace.MyClass.staticHelper = function(a) {
...
};
myapp.main = function() {
var MyClass = some.long.namespace.MyClass;
var staticHelper = some.long.namespace.MyClass.staticHelper;
staticHelper(new MyClass());
};
</CODE_SNIPPET>
<p>Do not alias namespaces.</p>
<BAD_CODE_SNIPPET>
myapp.main = function() {
var namespace = some.long.namespace;
namespace.MyClass.staticHelper(new namespace.MyClass());
};
</BAD_CODE_SNIPPET>
<p>Avoid accessing properties of an aliased type, unless it is an
enum.</p>
<CODE_SNIPPET>
/** @enum {string} */
some.long.namespace.Fruit = {
APPLE: 'a',
BANANA: 'b'
};
myapp.main = function() {
var Fruit = some.long.namespace.Fruit;
switch (fruit) {
case Fruit.APPLE:
...
case Fruit.BANANA:
...
}
};
</CODE_SNIPPET>
<BAD_CODE_SNIPPET>
myapp.main = function() {
var MyClass = some.long.namespace.MyClass;
MyClass.staticHelper(null);
};
</BAD_CODE_SNIPPET>
<p>Never create aliases in the global scope. Use them only in
function blocks.</p>
</SUBSUBSECTION>
</SUBSECTION> </SUBSECTION>
<SUBSECTION title="Filenames"> <SUBSECTION title="Filenames">
<p>Filenames should be all lowercase in order to avoid confusion on <p>Filenames should be all lowercase in order to avoid confusion on
@ -2220,6 +2319,38 @@
</td> </td>
</tr> </tr>
<tr>
<td><a name="tag-lends">@lends</a></td>
<td>
<tt>@lends objectName</tt><br/>
<tt>@lends {objectName}</tt>
<p><i>For example:</i></p>
<CODE_SNIPPET>
goog.object.extend(
Button.prototype,
/** @lends {Button.prototype} */ {
isButton: function() { return true; }
});
</CODE_SNIPPET>
</td>
<td>
Indicates that the keys of an object literal should
be treated as properties of some other object. This annotation
should only appear on object literals.<p/>
Notice that the name in braces is not a type name like
in other annotations. It's an object name. It names
the object on which the properties are "lent".
For example, <tt>@type {Foo}</tt> means "an instance of Foo",
but <tt>@lends {Foo}</tt> means "the constructor Foo".<p/>
The <a href="http://code.google.com/p/jsdoc-toolkit/wiki/TagLends">
JSDoc Toolkit docs</a> have more information on this
annotation.
</td>
<td>Yes</td>
</tr>
<tr> <tr>
<td><a name="tag-private">@private</a></td> <td><a name="tag-private">@private</a></td>
<td> <td>
@ -2674,7 +2805,6 @@
<li>@function</li> <li>@function</li>
<li>@ignore</li> <li>@ignore</li>
<li>@inner</li> <li>@inner</li>
<li>@lends</li>
<li>@link</li> <li>@link</li>
<li>@memberOf</li> <li>@memberOf</li>
<li>@name</li> <li>@name</li>
@ -3021,7 +3151,7 @@
</PARTING_WORDS> </PARTING_WORDS>
<p align="right"> <p align="right">
Revision 2.3 Revision 2.9
</p> </p>

20
objcguide.xml
View File

@ -4,7 +4,7 @@
<p align="right"> <p align="right">
Revision 2.20 Revision 2.21
</p> </p>
@ -932,6 +932,22 @@ Revision 2.20
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Avoid +new">
<SUMMARY>
Do not invoke the <code>NSObject</code> class method <code>new</code>,
nor override it in a subclass. Instead, use <code>alloc</code> and
<code>init</code> methods to instantiate retained objects.
</SUMMARY>
<BODY>
<p>
Modern Objective-C code explicitly calls <code>alloc</code> and an
<code>init</code> method to create and retain an object. As the
<code>new</code> class method is rarely used, it makes reviewing code
for correct memory management more difficult.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Keep the Public API Simple"> <STYLEPOINT title="Keep the Public API Simple">
<SUMMARY> <SUMMARY>
Keep your class simple; avoid "kitchen-sink" APIs. If a method doesn't Keep your class simple; avoid "kitchen-sink" APIs. If a method doesn't
@ -1556,7 +1572,7 @@ Revision 2.20
<HR/> <HR/>
<p align="right"> <p align="right">
Revision 2.20 Revision 2.21
</p> </p>