tiennm99/styleguide
1
0
Fork 0
mirror of https://github.com/tiennm99/styleguide.git synced 2026-06-17 12:49:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update C++ style guide to 3.274:

Browse Source 
- Change formatting rules of braced initializers.
 - Permit use of constexpr and allow constexpr global variables.
 - Allow all C++11 features except for those that are specifically banned.
 - Fix/add C99 format specifiers for ptrdiff_t and ssize_t.
 - Add lambda expressions to the list of explicitly banned C++11 features.
 - Relax "return type is always on the same line as the function name" rule.
 - Allow unique_ptr, discourage ownership transfer. Allow noncopyable std::move.
 - Allow system-specific includes after other includes.
 - Add boost/math/distributions to the set of permitted Boost libraries.

Update Objective-C style guide to 2.59:
 - Use instancetype as return type for example init methods.
 - Remove invalid +stringWithInt: call.
 - Remove reference to pre-Objective-C 2.0 declaration requirements.
 - Remove reference to Objective-C exception macros.
 - Remove reference to informal protocols as an alternative to optional methods.
 - Class headers should include comments documenting non-trivial interfaces.
 - Don't specify that blocks are preferable to methods as callbacks.
 - Specify "strong" and "weak" as comments for non-Objective-C pointers.
 - Replace improper reference to ownership of a retained object.
 - Clarify some aspects of method ordering rules.
 - Prefixes are required for shared code and optional for applications.
 - Clarify that nil pointers are safe as receivers, not necessarily parameters.
 - Clarify that delegate pointers should typically be zeroing weak pointers.
 - Allow a 100-column limit, except for projects that choose to use 80.

Update Python style guide to 2.59:
 - Add more examples of bad code to the default arguments section.
 - Allow ''' when ' is used as the single quote within a file.
 - Remove references to pychecker. Recommend pylint.
 - Add more examples to the indentation section.

Update JavaScript style guide to 2.93:
 - Add @nocompile.
 - Fix a few typos.
 - When wrapping lines, indent more deeply for child expressions.
 - Document that @const can be used on a constructor.
 - Update eval section to discourage using eval for RPC.
 - Update an example to avoid encouraging using numbers as booleans.
 - Allow for no indentation of @desc jsdoc tags.
 - Add @public discussion.

Update shell style guide to 1.26:
 - Add a section on style for case statements.

Update Common Lisp style guide to 1.23:
 - fare-matcher was superseded by optima.
 - Clarify wording regarding DYNAMIC-EXTENT.
This commit is contained in:
mark@chromium.org
2013-09-25 21:16:00 +00:00
parent d6c053f670
commit 7b24563e08
6 changed files with 1036 additions and 529 deletions
Download Patch File Download Diff File Expand all files Collapse all files
javascriptguide.xml
+143 -88
View File
@@ -3,7 +3,7 @@
<GUIDE title="Google JavaScript Style Guide">
<p class="revision">
Revision 2.82
Revision 2.93
</p>
<address>
@@ -78,7 +78,7 @@
<li>Never use the
<a href="https://developer.mozilla.org/en/JavaScript/Reference/Statements/const">
<code>const</code> keyword</a>
as it not supported in Internet Explorer.</li>
as it's not supported in Internet Explorer.</li>
</ul>
</SUMMARY>
<BODY>
@@ -112,8 +112,13 @@
lack of support in Internet Explorer).</p>
<p>A <code>@const</code> annotation on a method additionally
implies that the method should not be overridden in subclasses.
implies that the method cannot not be overridden in subclasses.
</p>
<p>A <code>@const</code> annotation on a constructor implies the
class cannot be subclassed (akin to <code>final</code> in Java).
</p>
</SUBSECTION>
<SUBSECTION title="Examples">
@@ -139,7 +144,7 @@
overwritten.
</p>
<p>The open source compiler will allow the symbol it to be
<p>The open source compiler will allow the symbol to be
overwritten because the constant is
<em>not</em> marked as <code>@const</code>.</p>
@@ -151,6 +156,15 @@
MyClass.fetchedUrlCache_ = new goog.structs.Map();
</CODE_SNIPPET>
<CODE_SNIPPET>
/**
* Class that cannot be subclassed.
* @const
* @constructor
*/
sloth.MyFinalClass = function() {};
</CODE_SNIPPET>
<p>In this case, the pointer can never be overwritten, but
value is highly mutable and <b>not</b> constant (and thus in
<code>camelCase</code>, not <code>ALL_CAPS</code>).</p>
@@ -187,7 +201,7 @@
// 2. Trying to do one thing on Internet Explorer and another on Firefox.
// I know you'd never write code like this, but throw me a bone.
[normalVersion, ffVersion][isIE]();
[ffVersion, ieVersion][isIE]();
var THINGS_TO_EAT = [apples, oysters, sprayOnCheese] // No semicolon here.
@@ -202,11 +216,12 @@
"called" resulting in an error.</li>
<li>You will most likely get a 'no such property in undefined'
error at runtime as it tries to call
<code>x[ffVersion][isIE]()</code>.</li>
<li><code>die</code> is called unless
<code>resultOfOperation()</code> is <code>NaN</code> and
<code>THINGS_TO_EAT</code> gets assigned the result of
<code>die()</code>.</li>
<code>x[ffVersion, ieVersion][isIE]()</code>.</li>
<li><code>die</code> is always called since the array minus 1 is
<code>NaN</code> which is never equal to anything (not even if
<code>resultOfOperation()</code> returns <code>NaN</code>) and
<code>THINGS_TO_EAT</code> gets assigned the result of
<code>die()</code>.</li>
</ol>
</SUBSECTION>
<SUBSECTION title="Why?">
@@ -265,7 +280,7 @@
Expression to define a function within a block:</p>
<CODE_SNIPPET>
if (x) {
var foo = function() {}
var foo = function() {};
}
</CODE_SNIPPET>
</BODY>
@@ -343,8 +358,7 @@
<a href="http://code.google.com/closure/library/">
the Closure Library
</a>
or something similar.
or a similar library function.
</p>
<CODE_SNIPPET>
function D() {
@@ -420,8 +434,7 @@
<p>The ability to create closures is perhaps the most useful and often
overlooked feature of JS. Here is
<a href="http://jibbering.com/faq/faq_notes/closures.html">
a good description of how closures work
</a>.</p>
a good description of how closures work</a>.</p>
<p>One thing to keep in mind, however, is that a closure keeps a pointer
to its enclosing scope. As a result, attaching a closure to a DOM
element can create a circular reference and thus, a memory leak. For
@@ -443,7 +456,7 @@
}
function bar(a, b) {
return function() { /* uses a and b */ }
return function() { /* uses a and b */ };
}
</CODE_SNIPPET>
</BODY>
@@ -451,53 +464,43 @@
<STYLEPOINT title="eval()">
<SUMMARY>
Only for deserialization (e.g. evaluating RPC responses)
Only for code loaders and REPL (Read–eval–print loop)
</SUMMARY>
<BODY>
<p><code>eval()</code> makes for confusing semantics and is dangerous
to use if the string being <code>eval()</code>'d contains user input.
There's usually a better, more clear, safer way to write your code, so
its use is generally not permitted. However <code>eval</code> makes
deserialization considerably easier than the non-<code>eval</code>
alternatives, so its use is acceptable for this task (for example, to
evaluate RPC responses).</p>
<p>Deserialization is the process of transforming a series of bytes into
an in-memory data structure. For example, you might write objects out
to a file as:</p>
There's usually a better, clearer, and safer way to write your code,
so its use is generally not permitted.</p>
<p>For RPC you can always use JSON and read the result using
<code>JSON.parse()</code> instead of <code>eval()</code>.</p>
<p>Let's assume we have a server that returns something like this:</p>
<CODE_SNIPPET>
users = [
{
name: 'Eric',
id: 37824,
email: 'jellyvore@myway.com'
},
{
name: 'xtof',
id: 31337,
email: 'b4d455h4x0r@google.com'
},
...
];
</CODE_SNIPPET>
<p>Reading these data back into memory is as simple as
<code>eval</code>ing the string representation of the file.</p>
<p>Similarly, <code>eval()</code> can simplify decoding RPC return
values. For example, you might use an <code>XMLHttpRequest</code>
to make an RPC, and in its response the server can return
JavaScript:</p>
<CODE_SNIPPET>
var userOnline = false;
var user = 'nusrat';
var xmlhttp = new XMLHttpRequest();
xmlhttp.open('GET', 'http://chat.google.com/isUserOnline?user=' + user, false);
xmlhttp.send('');
// Server returns:
// userOnline = true;
if (xmlhttp.status == 200) {
eval(xmlhttp.responseText);
{
"name": "Alice",
"id": 31502,
"email": "looking_glass@example.com"
}
// userOnline is now true.
</CODE_SNIPPET>
<BAD_CODE_SNIPPET>
var userInfo = eval(feed);
var email = userInfo['email'];
</BAD_CODE_SNIPPET>
<p>If the feed was modified to include malicious JavaScript code, then
if we use <code>eval</code> then that code will be executed.</p>
<CODE_SNIPPET>
var userInfo = JSON.parse(feed);
var email = userInfo['email'];
</CODE_SNIPPET>
<p>With <code>JSON.parse</code>, invalid JSON (including all executable
JavaScript) will cause an exception to be thrown.</p>
</BODY>
</STYLEPOINT>
@@ -768,7 +771,6 @@
* WRONG -- Do NOT do this.
*/
var foo = { get next() { return this.nextId++; } };
};
</BAD_CODE_SNIPPET>
</SUBSECTION>
@@ -1080,8 +1082,8 @@
// ...
}
// Parenthesis-aligned, one argument per line. Visually groups and
// emphasizes each individual argument.
// Parenthesis-aligned, one argument per line. Emphasizes each
// individual argument.
function bar(veryDescriptiveArgumentNumberOne,
veryDescriptiveArgumentTwo,
tableModelEventHandlerProxy,
@@ -1184,13 +1186,14 @@
}); // goog.scope
</CODE_SNIPPET>
</SUBSECTION>
<SUBSECTION title="More Indentation">
<p>In fact, except for
<a href="#Array_and_Object_literals">
array and object initializers
</a>, and passing anonymous functions, all wrapped lines
should be indented either left-aligned to the expression above, or
indented four spaces, not indented two spaces.</p>
<SUBSECTION title="Indenting wrapped lines">
<p>Except for <a href="#Array_and_Object_literals">array literals,
object literals</a>, and anonymous functions, all wrapped lines
should be indented either left-aligned to a sibling expression
above, or four spaces (not two spaces) deeper than a parent
expression (where "sibling" and "parent" refer to parenthesis
nesting level).
</p>
<CODE_SNIPPET>
someWonderfulHtml = '<div class="' + getClassesForWonderfulHtml()'">' +
@@ -1202,8 +1205,13 @@
thisIsAVeryLongVariableName =
hereIsAnEvenLongerOtherFunctionNameThatWillNotFitOnPrevLine();
thisIsAVeryLongVariableName = 'expressionPartOne' + someMethodThatIsLong() +
thisIsAnEvenLongerOtherFunctionNameThatCannotBeIndentedMore();
thisIsAVeryLongVariableName = siblingOne + siblingTwo + siblingThree +
siblingFour + siblingFive + siblingSix + siblingSeven +
moreSiblingExpressions + allAtTheSameIndentationLevel;
thisIsAVeryLongVariableName = operandOne + operandTwo + operandThree +
operandFour + operandFive * (
aNestedChildExpression + shouldBeIndentedMore);
someValue = this.foo(
shortArg,
@@ -2208,8 +2216,7 @@
<p>
We follow the
<a href="cppguide.xml#Comments">
C++ style for comments
</a> in spirit.
C++ style for comments</a> in spirit.
</p>
<p>All files, classes, methods and properties should be documented with
@@ -2229,9 +2236,8 @@
<SUBSECTION title="Comment Syntax">
<p>The JSDoc syntax is based on
<a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">
JavaDoc
</a>. Many tools extract metadata from JSDoc comments to perform
code validation and optimizations. These comments must be
JavaDoc</a>. Many tools extract metadata from JSDoc comments to
perform code validation and optimizations. These comments must be
well-formed.</p>
<CODE_SNIPPET>
@@ -2260,7 +2266,8 @@
};
</CODE_SNIPPET>
<p>You should not indent the <code>@fileoverview</code> command.</p>
<p>You should not indent the <code>@fileoverview</code> command. You do not have to
indent the <code>@desc</code> command.</p>
<p>Even though it is not preferred, it is also acceptable to line up
the description.</p>
@@ -2476,14 +2483,14 @@
*/
mynamespace.Request.prototype.initialize = function() {
// This method cannot be overridden in a subclass.
}
};
</CODE_SNIPPET>
</td>
<td>
<p>Marks a variable (or property) as read-only and suitable
for inlining.</p>
<p>A <code>@const</code> variable is a immutable pointer to
<p>A <code>@const</code> variable is an immutable pointer to
a value. If a variable or property marked as
<code>@const</code> is overwritten, JSCompiler will give
warnings.</p>
@@ -2532,7 +2539,10 @@
/** @define {boolean} */
var TR_FLAGS_ENABLE_DEBUG = true;
/** @define {boolean} */
/**
* @define {boolean} Whether we know at compile-time that
* the browser is IE.
*/
goog.userAgent.ASSUME_IE = false;
</CODE_SNIPPET>
</td>
@@ -2902,6 +2912,27 @@
</td>
</tr>
<tr>
<td><a name="tag-nocompile">@nocompile</a></td>
<td>
<code>@nocompile</code>
<p><i>For example:</i></p>
<CODE_SNIPPET>
/** @nocompile */
// JavaScript code
</CODE_SNIPPET>
</td>
<td>
Used at the top of a file to tell the compiler to parse this
file but not compile it.
Code that is not meant for compilation and should be omitted
from compilation tests (such as bootstrap code) uses this
annotation.
Use sparingly.
</td>
</tr>
<tr>
<td><a name="tag-nosideeffects">@nosideeffects</a></td>
<td>
@@ -2911,7 +2942,7 @@
/** @nosideeffects */
function noSideEffectsFn1() {
// ...
};
}
/** @nosideeffects */
var noSideEffectsFn2 = function() {
@@ -2943,7 +2974,7 @@
* @return {string} Human-readable representation of project.SubClass.
* @override
*/
project.SubClass.prototype.toString() {
project.SubClass.prototype.toString = function() {
// ...
};
</CODE_SNIPPET>
@@ -3000,9 +3031,7 @@
<td>
Used in conjunction with a trailing underscore on the method
or property name to indicate that the member is
<a href="#Visibility__private_and_protected_fields_">private</a>.
Trailing underscores may eventually be deprecated as tools are
updated to enforce <code>@private</code>.
<a href="#Visibility__private_and_protected_fields_">private</a> and final.
</td>
</tr>
@@ -3014,8 +3043,7 @@
<p><i>For example:</i></p>
<CODE_SNIPPET>
/**
* Sets the component's root element to the given element. Considered
* protected and final.
* Sets the component's root element to the given element.
* @param {Element} element Root element for the component.
* @protected
*/
@@ -3032,6 +3060,30 @@
</td>
</tr>
<tr>
<td><a name="tag-public">@public</a></td>
<td>
<code>@public</code><br/>
<code>@public {type}</code>
<p><i>For example:</i></p>
<CODE_SNIPPET>
/**
* Whether to cancel the event in internal capture/bubble processing.
* @public {boolean}
* @suppress {visiblity} Referencing this outside this package is strongly
* discouraged.
*/
goog.events.Event.prototype.propagationStopped_ = false;
</CODE_SNIPPET>
</td>
<td>
Used to indicate that the member or property is public. Variables and
properties are public by default, so this annotation is rarely necessary.
Should only be used in legacy code that cannot be easily changed to
override the visibility of members that were named as private variables.
</td>
</tr>
<tr>
<td><a name="tag-return">@return</a></td>
<td>
@@ -3136,6 +3188,9 @@
<code>
@suppress {warning1|warning2}
</code>
<code>
@suppress {warning1,warning2}
</code>
<p><i>For example:</i></p>
<CODE_SNIPPET>
/**
@@ -3148,7 +3203,7 @@
</td>
<td>
Suppresses warnings from tools. Warning categories are
separated by <code>|</code>.
separated by <code>|</code> or <code>,</code>.
</td>
</tr>
@@ -3166,7 +3221,7 @@
* @template T
*/
goog.bind = function(fn, thisObj, var_args) {
...
...
};
</CODE_SNIPPET>
</td>
@@ -3413,7 +3468,7 @@
<SUBSECTION title="Conditional (Ternary) Operator (?:)">
<p>Instead of this:</p>
<CODE_SNIPPET>
if (val != 0) {
if (val) {
return foo();
} else {
return bar();
@@ -3557,7 +3612,7 @@
</PARTING_WORDS>
<p align="right">
Revision 2.82
Revision 2.93
</p>