From 7ead64485b6955afcd21e8a537d38b283c5bba80 Mon Sep 17 00:00:00 2001 From: mmentovai Date: Mon, 4 Oct 2010 16:26:53 +0000 Subject: [PATCH] Update C++ style guide to 3.174: - 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. --- cppguide.xml | 58 ++++++------------- javascriptguide.xml | 136 +++++++++++++++++++++++++++++++++++++++++++- objcguide.xml | 20 ++++++- 3 files changed, 169 insertions(+), 45 deletions(-) diff --git a/cppguide.xml b/cppguide.xml index 2ef0f43..c02ce0b 100644 --- a/cppguide.xml +++ b/cppguide.xml @@ -4,7 +4,7 @@

-Revision 3.171 +Revision 3.174

@@ -3151,12 +3151,12 @@ Tashana Landray // Iterates over the contents of a GargantuanTable. Sample usage: - // GargantuanTable_Iterator* iter = table->NewIterator(); + // GargantuanTableIterator* iter = table->NewIterator(); // for (iter->Seek("foo"); !iter->done(); iter->Next()) { // process(iter->key(), iter->value()); // } // delete iter; - class GargantuanTable_Iterator { + class GargantuanTableIterator { ... }; @@ -3260,7 +3260,7 @@ Tashana Landray

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 describe any coding tricks you use, give an overview of the steps you go through, or explain why you chose to implement @@ -4356,9 +4356,10 @@ Tashana Landray

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 - one or two blank lines between functions, don't start or end - functions with a blank line, and be discriminating with your - use of blank lines inside functions. + one or two blank lines between functions, resist starting + functions with a blank line, don't end functions with a blank + line, and be discriminating with your use of blank lines + inside functions.

The basic principle is: The more code that fits on one screen, @@ -4369,39 +4370,16 @@ Tashana Landray whitespace.

- Don't start or end functions with blank lines: - - void Function() { - - // Unnecessary blank lines before and after - - } - -

-

- Don't start and end blocks with blank lines either: - - while (condition) { - // Unnecessary blank line after - - } - if (condition) { - - // Unnecessary blank line before - } - - However, it's okay to add blank lines between a chain of - if-else blocks: - - if (condition) { - // Some lines of code too small to move to another function, - // followed by a blank line. - - } else { - // Another block of code - } - + Some rules of thumb to help when blank lines may be useful:

+ @@ -4551,7 +4529,7 @@ Tashana Landray

-Revision 3.171 +Revision 3.174

diff --git a/javascriptguide.xml b/javascriptguide.xml index 2f839cd..f27555d 100644 --- a/javascriptguide.xml +++ b/javascriptguide.xml @@ -3,7 +3,7 @@

- Revision 2.3 + Revision 2.9

@@ -173,6 +173,32 @@ + + No + +

Do not do this:

+ + if (x) { + function foo() {} + } + + +

While most script engines support Function Declarations within blocks + it is not part of ECMAScript (see + ECMA-262, + 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:

+ + if (x) { + var foo = function() {} + } + + + + Yes @@ -548,6 +574,20 @@ avoided.

 + + + 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.

+ + @@ -683,6 +723,65 @@ + +

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.

+ + /** + * @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()); + }; + +

Do not alias namespaces.

+ + myapp.main = function() { + var namespace = some.long.namespace; + namespace.MyClass.staticHelper(new namespace.MyClass()); + }; + +

Avoid accessing properties of an aliased type, unless it is an + enum.

+ + /** @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: + ... + } + }; + + + myapp.main = function() { + var MyClass = some.long.namespace.MyClass; + MyClass.staticHelper(null); + }; + +

Never create aliases in the global scope. Use them only in + function blocks.

+

Filenames should be all lowercase in order to avoid confusion on @@ -2220,6 +2319,38 @@ + + @lends + + @lends objectName
+ @lends {objectName} +

For example:

+ + goog.object.extend( + Button.prototype, + /** @lends {Button.prototype} */ { + isButton: function() { return true; } + }); + + + + 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.

+ + 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, @type {Foo} means "an instance of Foo", + but @lends {Foo} means "the constructor Foo".

+ + The + JSDoc Toolkit docs have more information on this + annotation. + + Yes + + @private @@ -2674,7 +2805,6 @@

  • @function
  • @ignore
  • @inner
    • -
  • @lends
  • @link
  • @memberOf
  • @name
    • @@ -3021,7 +3151,7 @@

    - Revision 2.3 + Revision 2.9

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

    -Revision 2.20 +Revision 2.21

    @@ -932,6 +932,22 @@ Revision 2.20 + + + Do not invoke the NSObject class method new, + nor override it in a subclass. Instead, use alloc and + init methods to instantiate retained objects. + + +

    + Modern Objective-C code explicitly calls alloc and an + init method to create and retain an object. As the + new class method is rarely used, it makes reviewing code + for correct memory management more difficult. +

    + +     + Keep your class simple; avoid "kitchen-sink" APIs. If a method doesn't @@ -1556,7 +1572,7 @@ Revision 2.20

    -Revision 2.20 +Revision 2.21