From cd4ce0fff0216d668a6abd553c90879b68b953f8 Mon Sep 17 00:00:00 2001 From: mmentovai Date: Tue, 29 Mar 2011 20:30:47 +0000 Subject: [PATCH] Update C++ style guide to 3.188: - Revise "Smart Pointers" section. - Clarify that it's OK to have spaces after '#' in a preprocessor directive, even though '#' itself must not be indented. - Revise "TODO Comments" section. - Fix wording. - Explicitly recommend foo.h be the first file #included by foo_test.cc. Update Objective-C style guide to 2.24: - Clarify the spacing of @property declarations. - Add "Overridden NSObject Method Placement" section. - Explicitly permit blank lines around @interface, @implementation, and @end. Update JavaScript style guide to 2.20: - Provide additional guidance with respect to the compiler. - Add {function(new:Type)} as a type syntax for constructors of Type. - Revise "Method and Function Comments" section. - Harmonize text and example in the "Passing Anonymous Functions" section. - Explicitly state that @param and @return types must be enclosed in braces. - Add documentation on the UNKNOWN type. - Replace a CODE_SNIPPET with BAD_CODE_SNIPPET in the "Internet Explorer's Conditional Comments" section. - Remove a redundant "Expand for more information" in the "Naming" section and fully spell out "information" in the "Code Formatting" section. - Provide a positive example in the "Multiline string literals" section. - Provide guidance for indentation within nested functions. Update Python style guide to 2.20: - Clarify shebang rule. --- cppguide.xml | 101 +++++++++++++++++++------------ javascriptguide.xml | 144 +++++++++++++++++++++++++++++++++++++------- objcguide.xml | 37 ++++++++++-- pyguide.html | 58 +++++++++--------- 4 files changed, 243 insertions(+), 97 deletions(-) diff --git a/cppguide.xml b/cppguide.xml index c335fc7..a3e45c2 100644 --- a/cppguide.xml +++ b/cppguide.xml @@ -4,7 +4,7 @@

-Revision 3.180 +Revision 3.188

@@ -161,7 +161,7 @@ Tashana Landray header files.

- You can significantly minimize the number of header files you + You can significantly reduce the number of header files you need to include in your own header files by using forward declarations. For example, if your header file uses the File class in ways that do not require access to @@ -355,7 +355,7 @@ Tashana Landray

All of a project's header files should be - listed as descentants of the project's source directory + listed as descendants of the project's source directory without use of UNIX directory shortcuts . (the current directory) or .. (the parent directory). For example, @@ -367,8 +367,8 @@ Tashana Landray #include "base/logging.h"

- In dir/foo.cc, whose main purpose is - to implement or test the stuff in + In dir/foo.cc or dir/foo_test.cc, + whose main purpose is to implement or test the stuff in dir2/foo2.h, order your includes as follows:

@@ -1464,34 +1464,46 @@ Tashana Landray If you actually need pointer semantics, scoped_ptr is great. You should only use std::tr1::shared_ptr - under very specific conditions, such as when objects need to be - held by STL containers. You should never use auto_ptr. + with a non-const referent when it is truly necessary to share ownership + of an object (e.g. inside an STL container). You should never use + auto_ptr. -

- "Smart" pointers are objects that act like pointers but have - added semantics. When a scoped_ptr is - destroyed, for instance, it deletes the object it's pointing - to. shared_ptr is the same way, but implements - reference-counting so only the last pointer to an object - deletes it. -

-

- Generally speaking, we prefer that we design code with clear - object ownership. The clearest object ownership is obtained by - using an object directly as a field or local variable, without - using pointers at all. On the other extreme, by their very definition, - reference counted pointers are owned by nobody. The problem with - this design is that it is easy to create circular references or other - strange conditions that cause an object to never be deleted. - It is also slow to perform atomic operations every time a value is - copied or assigned. -

-

- Although they are not recommended, reference counted pointers are - sometimes the simplest and most elegant way to solve a problem. - -

+ + "Smart" pointers are objects that act like pointers, but automate + management of the underlying memory. + + + Smart pointers are extremely useful for preventing memory leaks, and + are essential for writing exception-safe code. They also formalize + and document the ownership of dynamically allocated memory. + + + We prefer designs in which objects have single, fixed owners. Smart + pointers which enable sharing or transfer of ownership can act as a + tempting alternative to a careful design of ownership semantics, + leading to confusing code and even bugs in which memory is never + deleted. The semantics of smart pointers (especially + auto_ptr) can be nonobvious and confusing. The + exception-safety benefits of smart pointers are not decisive, since + we do not allow exceptions. + + +
+
scoped_ptr
+
Straightforward and risk-free. Use wherever appropriate.
+
auto_ptr
+
Confusing and bug-prone ownership-transfer semantics. Do not use. +
+
shared_ptr
+
+ Safe with const referents (i.e. shared_ptr<const + T>). Reference-counted pointers with non-const referents + can occasionally be the best design, but try to rewrite with single + owners where possible. +
+
+ @@ -3456,14 +3468,20 @@ Tashana Landray

TODOs should include the string TODO in - all caps, followed by your + all caps, followed by the name, e-mail address, or other identifier - in parentheses. A colon is optional. The main purpose is to have - a consistent TODO format searchable by the person - adding the comment (who can provide more details upon request). A - TODO is not a commitment to provide the fix yourself. + of the person who can best provide context about the problem + referenced by the TODO. A colon is optional. The main + purpose is to have a consistent TODO format that can be + searched to find the person who can provide more details upon request. + A TODO is not a commitment that the person referenced + will fix the problem. Thus when you create a TODO, it is + almost always your + + name + that is given.

@@ -4105,12 +4123,12 @@ Tashana Landray - Preprocessor directives should not be indented but should - instead start at the beginning of the line. + The hash mark that starts a preprocessor directive should + always be at the beginning of the line.

- Even when pre-processor directives are within the body of + Even when preprocessor directives are within the body of indented code, the directives should start at the beginning of the line.

@@ -4119,6 +4137,9 @@ Tashana Landray if (lopsided_score) { #if DISASTER_PENDING // Correct -- Starts at beginning of line DropEverything(); + # if NOTIFY // OK but not required -- Spaces after # + NotifyClient(); + # endif #endif BackToNormal(); } @@ -4529,7 +4550,7 @@ Tashana Landray

-Revision 3.180 +Revision 3.188

diff --git a/javascriptguide.xml b/javascriptguide.xml index 325b016..61e0a24 100644 --- a/javascriptguide.xml +++ b/javascriptguide.xml @@ -3,7 +3,7 @@

- Revision 2.11 + Revision 2.20

@@ -504,6 +504,15 @@ at compile time; whitespace after the slash will result in tricky errors; and while most script engines support this, it is not part of ECMAScript.

+

Use string concatenation instead:

+ + var myString = 'A rather long string of English text, an error message ' + + 'actually that just keeps going and going -- an error ' + + 'message to make the Energizer bunny blush (right through ' + + 'those Schwarzenegger shades)! Where was I? Oh yes, ' + + 'you\'ve got an error and all the extraneous whitespace is ' + + 'just gravy. Have a nice day.'; + @@ -579,11 +588,11 @@ No

Don't do this:

- + var f = function () { /*@cc_on if (@_jscript) { return 2* @*/ 3; /*@ } @*/ }; - +

Conditional Comments hinder automated tools as they can vary the JavaScript syntax tree at runtime.

@@ -597,7 +606,6 @@ variableNamesLikeThis, ClassNamesLikeThis, EnumNamesLikeThis, methodNamesLikeThis, and SYMBOLIC_CONSTANTS_LIKE_THIS.

-

Expand for more information.

@@ -830,7 +838,7 @@ - Expand for more info. + Expand for more information.

We follow the C++ formatting rules in spirit, with the following additional clarifications.

@@ -943,19 +951,29 @@ // ... } +

When the function call is itself indented, you're free to start the + 4-space indent relative to the beginning of the original statement + or relative to the beginning of the current function call. + The following are all acceptable indentation styles.

+ + if (veryLongFunctionNameA( + veryLongArgumentName) || + veryLongFunctionNameB( + veryLongArgumentName)) { + veryLongFunctionNameC(veryLongFunctionNameD( + veryLongFunctioNameE( + veryLongFunctionNameF))); + } +

When declaring an anonymous function in the list of arguments for a function call, the body of the function is indented two spaces - from the left edge of the function call or the statement, not two - spaces from the left edge of the function keyword. This is to make - the body of the anonymous function easier to read (i.e. not be all - squished up into the right half of the screen).

+ from the left edge of the statement, or two spaces from the left + edge of the function keyword. This is to make the body of the + anonymous function easier to read (i.e. not be all squished up into + the right half of the screen).

- var names = items.map(function(item) { - return item.name; - }); - prefix.something.reallyLongFunctionName('whatever', function(a1, a2) { if (a1.equals(a2)) { someOtherLongFunctionName(a1); @@ -963,6 +981,12 @@ andNowForSomethingCompletelyDifferent(a2.parrot); } }); + + var names = prefix.something.myExcellentMapFunction( + verboselyNamedCollectionOfItems, + function(item) { + return item.name; + }); @@ -1063,7 +1087,12 @@

We recommend the use of the JSDoc annotations @private and @protected to indicate visibility levels for classes, functions, and properties.

- +

The --jscomp_warning=visibility compiler flag turns on compiler + warnings for visibility violations. See + + Closure Compiler + Warnings. +

@private global variables and functions are only accessible to code in the same file.

Constructors marked @private may only be instantiated by @@ -1301,6 +1330,18 @@ + + Function new Type + + {function(new:goog.ui.Menu, string)}
+ A constructor that takes one argument (a string), and + creates a new instance of goog.ui.Menu when called + with the 'new' keyword. + + Specifies the constructed type of a constructor. + + + Variable arguments @@ -1361,6 +1402,14 @@ Indicates that the variable can take on any type. + + + The UNKNOWN type + {?} + Indicates that the variable can take on any type, + and the compiler should not type-check any uses of it. + + @@ -1900,10 +1949,10 @@ -

A description must be provided along with parameters. Use full - sentences. Method descriptions should start with a sentence written - in the third person declarative voice.

- +

A description must be provided along with parameters. + When appropriate or necessary, use full sentences. Method + descriptions should start with a sentence written in the third + person declarative voice.

/** * Converts text to some completely different text. @@ -2064,7 +2113,29 @@ - + + +

The compiler has limited support for template types. It can only + infer the type of this inside an anonymous function + literal from the type of the this argument and whether the + this argument is missing.

+ + + /** + * @param {function(this:T, ...)} fn + * @param {T} thisObj + * @param {...*} var_args + * @template T + */ + goog.bind = function(fn, thisObj, var_args) { + ... + }; + // Possibly generates a missing property warning. + goog.bind(function() { this.someProperty; }, new SomeClass()); + // Generates an undefined this warning. + goog.bind(function() { this.someProperty; }); + + @@ -2096,7 +2167,10 @@ @@ -2121,7 +2195,10 @@ type. When writing descriptions for boolean parameters, prefer "Whether the component is visible" to "True if the component is visible, false otherwise". If there is no return - value, do not use an @return tag. + value, do not use an @return tag.

+ + Type names must be enclosed in curly braces. If the type + is omitted, the compiler will not type-check the return value.

@@ -2757,7 +2834,28 @@ - + + + + + + @@ -3155,7 +3253,7 @@

- Revision 2.11 + Revision 2.20

diff --git a/objcguide.xml b/objcguide.xml index a81ef1f..8f4de87 100644 --- a/objcguide.xml +++ b/objcguide.xml @@ -4,7 +4,7 @@

-Revision 2.21 +Revision 2.24

@@ -169,7 +169,7 @@ Revision 2.21

- An example source file, demonstating the correct commenting and spacing + An example source file, demonstrating the correct commenting and spacing for the @implementation of an interface. It also includes the reference implementations for important methods like getters and setters, init, and dealloc. @@ -229,6 +229,18 @@ Revision 2.21 @end +

+ Blank lines before and after @interface, + @implementation, and @end are optional. If your + @interface declares instance variables, as most do, any blank + line should come after the closing brace (}). +

+

+ Unless an interface or implementation is very short, such as when declaring + a handful of private methods or a bridge class, adding blank lines usually + helps readability. +

+ @@ -918,6 +930,21 @@ Revision 2.21 + + + It is strongly recommended and typical practice to place overridden + methods of NSObject at the top of an + @implementation. + + + This commonly applies (but is not limited) to the init..., + copyWithZone:, and dealloc methods. + init... methods should be grouped together, followed by + the copyWithZone: method, and finally the + dealloc method. + + + Don't initialize variables to 0 or nil in the @@ -1368,7 +1395,9 @@ Revision 2.21

A property's associated instance variable's name must conform to the trailing _ requirement. The property's name should be the same as its - associated instance variable without the trailing _. + associated instance variable without the trailing _. The optional + space between the @property and the opening parenthesis + should be omitted, as seen in the examples.

Use the @synthesize directive to rename the property correctly. @@ -1572,7 +1601,7 @@ Revision 2.21

-Revision 2.21 +Revision 2.24

diff --git a/pyguide.html b/pyguide.html index 50a9d01..475cebf 100644 --- a/pyguide.html +++ b/pyguide.html @@ -100,7 +100,7 @@

Google Python Style Guide

- Revision 2.19 + Revision 2.20

@@ -134,7 +134,7 @@
+SemicolonsLine lengthParenthesesIndentationBlank LinesWhitespaceShebang LineCommentsClassesStringsTODO CommentsImports formattingStatementsAccess ControlNamingMain
Used with method, function and constructor calls to document - the arguments of a function. + the arguments of a function.

+ + Type names must be enclosed in curly braces. If the type + is omitted, the compiler will not type-check the parameter.

Fully supported.
Fully supported.
Yes
@template + @template +

For example:

+ + /** + * @param {function(this:T, ...)} fn + * @param {T} thisObj + * @param {...*} var_args + * @template T + */ + goog.bind = function(fn, thisObj, var_args) { + ... + }; + + 		+ This annotation can be used to declare a template typename. + Yes with limitations.
@externs
Python Style Rules
-Semicolons Line length Parentheses Indentation Blank Lines Whitespace Python Interpreter Comments Classes Strings TODO Comments Imports formatting Statements Access Control Naming Main
@@ -1370,36 +1370,34 @@ from sound.effects import echo -
-

Python Interpreter

- - link - ▶ -
- Modules should begin with - - #!/usr/bin/env python<version> -
-