From c8c76a2389420f017538073aec28969287ebaf53 Mon Sep 17 00:00:00 2001 From: "mark@chromium.org" Date: Wed, 28 Nov 2012 20:26:27 +0000 Subject: [PATCH] Update C++ style guide to 3.231: - Clarify that sentence-like non-sentence comments are permitted. - Note that older code with incorrect #include ordering should be fixed. - Revamp the section on default function arguments. - Avoid explicitly recommending Init() methods. - C++11: permit "auto". - C++11: permit ">>" in place of "> >". - C++11: permit range-based "for". - C++11: permit variadic macros (already permitted as a C++03 extension). - C++11: permit "LL" and "ULL" literal suffixes (already permitted as a C++03 extension). - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - C++11: permit new features in and the portion of that does not require initializer lists. - Revise rules on forward declarations: explicitly forbid forward-declared functions, do not mandate forward declarations, discourage forward-declared templates. - Remove the rule requiring "const" qualifiers for member functions to be on the same line as the closing parenthesis of the parameter list. - Fix typo: "unnamed namespaces." - C++11: permit local types as template parameters. - Fix typo: "unfamiliar." - Relax RTTI rules to permit its use, but warn about its abuse. - C++11: permit nullptr and nullptr_t. Revise text referring to NULL to refer more generically to null pointers. - Remove the "don't go crazy with const" rule. - Fix typo: "dir/foo2" should bee "dir2/foo2." - Remove reference to a specific GCC version. Update Objective-C style guide to 2.48: - Revise method declaration and invocation formatting rules for long names. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. Top-of-file comments are not required. - Fix dead link in the "nil Checks" section. - Cover ARC. - Specify that @private is only required for instance variables in header files. - Permit NSNumber literals. - Change the naming convention for instance variables from trailing underscore to leading underscore, allowing a wide exception for existing code and projects. - Fix description of BOOL with respect to its signedness. Update Python style guide to 2.45: - Recommend "pylint: disable" over "pylint: disable-msg." - Fix case-sensitive anchor. - Provide a better explanation of the problems with catch-all "except:." - Permit "map" and "filter" in absence of inlined lambdas. Update JavaScript style guide to 2.64: - Clarify rules for requiring and providing inner dependencies on classes. - Clarify semicolons for functions. - Note proper namespace and filename casing. - Fix typos: "@extends." - Permit parentheses to be omitted on unions. - Don't require method descriptions when obvious. - "in" is a keyword, put it in . - New "Aliasing with goog.scope" section. - Rewrite the "Constants" section. - Remove the recommendation to use join() to build strings. - Add the "@expose" annotation. - Fix the "@suppress" example. - Remove reference alternate cast syntax. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - Say that "use strict" is not required. - Fix links to "optional" section. - Rewrite "JavaScript Types" section. - Fix typos: "parameterizes," "converted." - Prefer in-constructor field initialization. - Add a section on "delete" and null-assignment. - Add a note about optional JSDoc comments on enum values. - State explicitly that dot operators belong at the ends of lines. - Add "@dict" and "@struct" annotations. - Add links to the JavaScript Types section. - Require (rather than encourage) compiling. Update HTML/CSS style guide to 2.19: - Rephrased quotation guidelines. - Updated W3C I18N article reference. - Fixed revision number. Update styleguide.xsl to 1.34: - Fix error in RefreshVisibilityFromHashParam when a URL fragment points to a named anchor within a section, as used by the JavaScript style guide. --- cppguide.xml | 589 ++++++++++++++++++++++-------------- htmlcssguide.xml | 91 +++--- javascriptguide.xml | 715 ++++++++++++++++++++++++++++++++------------ objcguide.xml | 432 +++++++++++++++----------- pyguide.html | 25 +- styleguide.xsl | 4 +- 6 files changed, 1209 insertions(+), 647 deletions(-) diff --git a/cppguide.xml b/cppguide.xml index 480876c..65446b0 100644 --- a/cppguide.xml +++ b/cppguide.xml @@ -4,7 +4,7 @@

-Revision 3.199 +Revision 3.231

@@ -145,80 +145,71 @@ Tashana Landray - + - Don't use an #include when a forward declaration - would suffice. + You may forward declare ordinary classes in order to avoid + unnecessary #includes. -

- When you include a header file you introduce a dependency that - will cause your code to be recompiled whenever the header file - changes. If your header file includes other header files, any - change to those files will cause any code that includes your - header to be recompiled. Therefore, we prefer to minimize - includes, particularly includes of header files in other - header files. -

-

- 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 - the declaration of the File class, your header - file can just forward declare class File; instead - of having to #include "file/base/file.h". -

-

- How can we use a class Foo in a header file - without access to its definition? -

-
    -
  • We can declare data members of type Foo* or - Foo&. -
    • -
  • We can declare (but not define) functions with arguments, - and/or return values, of type Foo. (One - exception is if an argument Foo - or const Foo& has a - non-explicit, one-argument constructor, - - in which case we need the full definition to support - automatic type conversion.) -
    • -
  • We can declare static data members of type - Foo. This is because static data members - are defined outside the class definition. -
    • -
-

- On the other hand, you must include the header file for - Foo if your class subclasses Foo or - has a data member of type Foo. -

-

- Sometimes it makes sense to have pointer (or better, - scoped_ptr) - members instead of object members. However, this complicates code - readability and imposes a performance penalty, so avoid doing - this transformation if the only purpose is to minimize includes - in header files. -

-

- Of course, .cc files typically do require the - definitions of the classes they use, and usually have to - include several header files. -

- - If you use a symbol Foo in your source file, you - should bring in a definition for Foo yourself, - either via an #include or via a forward declaration. Do not - depend on the symbol being brought in transitively via headers - not directly included. One exception is if Foo - is used in myfile.cc, it's ok to #include (or - forward-declare) Foo in myfile.h, - instead of myfile.cc. - + + A "forward declaration" is a declaration of a class, function, + or template without an associated definition. #include + lines can often be replaced with forward declarations of whatever + symbols are actually used by the client code. + + +
    +
  • Unnecessary #includes force the compiler to open + more files and process more input.
    • +
  • They can also force your code to be recompiled more often, due + to changes in the header.
    • +
+ + +
    +
  • It can be difficult to determine the correct form of a + forward declaration in the presence of features like templates, + typedefs, default parameters, and using declarations.
    • +
  • It can be difficult to determine whether a forward declaration + or a full #include is needed for a given piece of code, + particularly when implicit conversion operations are involved. In + extreme cases, replacing an #include with a forward + declaration can silently change the meaning of code.
    • +
  • Forward declaring multiple symbols from a header can be more + verbose than simply #includeing the header.
    • +
  • Forward declarations of functions and templates can prevent + the header owners from making otherwise-compatible changes to + their APIs; for example, widening a parameter type, or adding + a template parameter with a default value.
    • +
  • Forward declaring symbols from namespace std:: + usually yields undefined behavior.
    • +
  • Structuring code to enable forward declarations (e.g. + using pointer members instead of object members) can make the + code slower and more complex.
    • +
  • The practical efficiency benefits of forward declarations are + unproven.
    • +
+ + +
    +
  • When using a function declared in a header file, always + #include that header.
    • +
  • When using a class template, prefer to #include its + header file.
    • +
  • When using an ordinary class, relying on a forward declaration + is OK, but be wary of situations where a forward declaration may + be insufficient or incorrect; when in doubt, just + #include the appropriate header.
    • +
  • Do not replace data members with pointers just to avoid an + #include.
    • +
+ Always #include the file that actually provides the + declarations/definitions you need; do not rely on the symbol being + brought in transitively via headers not directly included. One + exception is that myfile.cc may rely on + #includes and forward declarations from its corresponding + header file myfile.h. + @@ -367,7 +358,7 @@ Tashana Landray

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

@@ -382,7 +373,7 @@ Tashana Landray .h files.

- With the preferred ordering, if dir/foo2.h + With the preferred ordering, if dir2/foo2.h omits any necessary includes, the build of dir/foo.cc or dir/foo_test.cc will break. @@ -399,8 +390,9 @@ Tashana Landray

- Within each section it is nice to order the includes - alphabetically. + Within each section the includes should be ordered alphabetically. + Note that older code might not conform to this rule and should be + fixed when convenient.

For example, the includes in @@ -461,7 +453,7 @@ Tashana Landray (also hierarchical) name axis provided by classes.

- Use of unnamed spaces in header files can easily cause + Use of unnamed namespaces in header files can easily cause violations of the C++ One Definition Rule (ODR).

@@ -840,9 +832,8 @@ Tashana Landray - In general, constructors should merely set member variables to their - initial values. Any complex initialization should go in an explicit - Init() method. + Avoid doing complex initialization in constructors (in particular, + initialization that can fail or that requires virtual method calls). @@ -882,10 +873,9 @@ Tashana Landray - If your object requires non-trivial initialization, consider - having an explicit Init() method. In particular, - constructors should not call virtual functions, attempt to raise - errors, access potentially uninitialized global variables, etc. + Constructors should never call virtual functions or attempt to raise + non-fatal failures. If your object requires non-trivial + initialization, consider using a factory function or Init() method. @@ -1551,7 +1541,7 @@ Tashana Landray Defining a parameter as reference avoids ugly code like (*pval)++. Necessary for some applications like copy constructors. Makes it clear, unlike with pointers, that - NULL is not a possible value. + a null pointer is not a possible value. References can be confusing, as they have value syntax but @@ -1577,10 +1567,10 @@ Tashana Landray However, there are some instances where using const T* is preferable to const T& for input parameters. For example: - - You want to pass in NULL. - - The function saves a pointer or reference to the input. +
    +
  • You want to pass in a null pointer.
    • +
  • The function saves a pointer or reference to the input.
    • +
Remember that most of the time input parameters are going to be @@ -1643,35 +1633,47 @@ Tashana Landray - We do not allow default function parameters, except in - a few uncommon situations explained below. + We do not allow default function parameters, except in limited + situations as explained below. Simulate them with function + overloading instead, if appropriate. - Often you have a function that uses lots of default values, - but occasionally you want to override the defaults. Default + Often you have a function that uses default values, but + occasionally you want to override the defaults. Default parameters allow an easy way to do this without having to - define many functions for the rare exceptions. + define many functions for the rare exceptions. Compared to + overloading the function, default arguments have a cleaner + syntax, with less boilerplate and a clearer distinction + between 'required' and 'optional' arguments. - People often figure out how to use an - API by looking at existing code that uses it. - Default parameters are more difficult to maintain because - copy-and-paste from previous code may not reveal all the - parameters. Copy-and-pasting of code segments can cause major - problems when the default arguments are not appropriate for - the new code. + Function pointers are confusing in the presence of default + arguments, since the function signature often doesn't match + the call signature. Adding a default argument to an existing + function changes its type, which can cause problems with code + taking its address. Adding function overloads avoids these + problems. In addition, default parameters may result in + bulkier code since they are replicated at every call-site -- + as opposed to overloaded functions, where "the default" + appears only in the function definition.

- Except as described below, we require all arguments to be - explicitly specified, to force programmers to consider the API - and the values they are passing for each argument rather than - silently accepting defaults they may not be aware of. + While the cons above are not that onerous, they still + outweigh the (small) benefits of default arguments over + function overloading. So except as described below, we + require all arguments to be explicitly specified.

- One specific exception is when default arguments are used to - simulate variable-length argument lists. + One specific exception is when the function is a static + function (or in an unnamed namespace) in a .cc file. In + this case, the cons don't apply since the function's use is + so localized. +

+

+ Another specific exception is when default arguments are + used to simulate variable-length argument lists.

// Support up to 4 params by using a default empty AlphaNum. @@ -1851,57 +1853,107 @@ Tashana Landray - We do not use Run Time Type Information (RTTI). + Avoid using Run Time Type Information (RTTI). RTTI allows a programmer to query the C++ class of an - object at run time. + object at run time. This is done by use of typeid or + dynamic_cast. + +

+ Querying the type of an object at run-time frequently means a + design problem. Needing to know the type of an + object at runtime is often an indication that + the design of your class hierarchy is flawed. +

+

+ Undisciplined use of RTTI makes code hard to maintain. It can + lead to type-based decision trees or switch statements scattered + throughout the code, all of which must be examined when making + further changes. +

+

- It is useful in some unittests. For example, it is useful in - tests of factory classes where the test has to verify that a - newly created object has the expected dynamic type. + The standard alternatives to RTTI (described below) require + modification or redesign of the class hierarchy in question. + Sometimes such modifications are infeasible or undesirable, + particularly in widely-used or mature code.

- In rare circumstances, it is useful even outside of - tests. + RTTI can be useful in some unit tests. For example, it is useful in + tests of factory classes where the test has to verify that a + newly created object has the expected dynamic type. It is also + useful in managing the relationship between objects and their mocks.

+

+ RTTI is useful when considering multiple abstract objects. Consider + + bool Base::Equal(Base* other) = 0; + bool Derived::Equal(Base* other) { + Derived* that = dynamic_cast<Derived*>(other); + if (that == NULL) + return false; + ... + } + +

+ - - A query of type during run-time typically means a - design problem. If you need to know the type of an - object at runtime, that is often an indication that - you should reconsider the design of your class. -

- Do not use RTTI, except in unittests. If you find yourself - in need of writing code that behaves differently based on - the class of an object, consider one of the alternatives to - querying the type. + RTTI has legitimate uses but is prone to abuse, so you must + be careful when using it. You may use it freely + in unittests, but avoid it when possible in other code. + In particular, think twice before using RTTI in new code. + If you find yourself needing to write code that behaves differently + based on the class of an object, consider one of the following + alternatives to querying the type: +

    +
  • + Virtual methods are the preferred way of executing different + code paths depending on a specific subclass type. This puts + the work within the object itself. +
    • +
  • + If the work belongs outside the object and instead in some + processing code, consider a double-dispatch solution, such + as the Visitor design pattern. This allows a facility + outside the object itself to determine the type of class + using the built-in type system. +
    • +

- Virtual methods are the preferred way of executing different - code paths depending on a specific subclass type. This puts - the work within the object itself. -

-

- If the work belongs outside the object and instead in some - processing code, consider a double-dispatch solution, such - as the Visitor design pattern. This allows a facility - outside the object itself to determine the type of class - using the built-in type system. -

-

- If you think you truly cannot use those ideas, + When the logic of a program guarantees that a given instance + of a base class is in fact an instance of a particular derived class, + then a dynamic_cast may be used freely on the object. - you may use RTTI. But think twice - about it. :-) Then think twice again. + Usually one can use a + static_cast as an alternative in such situations. +

+

+ Decision trees based on type are a strong indication that your + code is on the wrong track. + + if (typeid(*data) == typeid(D1)) { + ... + } else if (typeid(*data) == typeid(D2)) { + ... + } else if (typeid(*data) == typeid(D3)) { + ... + + Code such as this usually breaks when additional subclasses are + added to the class hierarchy. Moreover, when properties of a subclass + change, it is difficult to find and modify all the affected code segments. +

+

Do not hand-implement an RTTI-like workaround. The arguments against RTTI apply just as much to workarounds like class - hierarchies with type tags. + hierarchies with type tags. Moreover, workarounds disguise your + true intent.

@@ -1951,13 +2003,11 @@ Tashana Landray other pointer types. Use this only if you know what you are doing and you understand the aliasing issues. - -
  • Do not use dynamic_cast except in test code. - If you need to know type information at runtime in this way - outside of a unittest, you probably have a design - flaw.
    • +

    See the RTTI section + for guidance on the use of dynamic_cast. +

    @@ -2108,8 +2158,7 @@ Tashana Landray - We strongly recommend that you use const whenever - it makes sense to do so. + Use const whenever it makes sense. @@ -2163,13 +2212,6 @@ Tashana Landray construction. -

    - However, do not go crazy with const. Something like - const int * const * const x; is likely - overkill, even if it accurately describes how const x is. - Focus on what's really useful to know: in this case, - const int** x is probably sufficient. -

    The mutable keyword is allowed but is unsafe when used with threads, so thread safety should be carefully @@ -2183,9 +2225,11 @@ Tashana Landray readable because it's more consistent: it keeps the rule that const always follows the object it's describing. However, this consistency argument doesn't - apply in this case, because the "don't go crazy" dictum - eliminates most of the uses you'd have to be consistent with. - + apply in codebases with few deeply-nested pointer + expressions since most const expressions have + only one const, and it applies to the + underlying value. In such cases, there's no consistency to + maintain. Putting the const first is arguably more readable, since it follows English in putting the "adjective" (const) before the "noun" (int). @@ -2494,10 +2538,11 @@ Tashana Landray - +

    Use 0 for integers, 0.0 for reals, - NULL for pointers, and '\0' for chars. + nullptr (or NULL) for pointers, + and '\0' for chars.

    @@ -2505,13 +2550,17 @@ Tashana Landray This is not controversial.

    + + For pointers (address values), there is a choice between 0 - and NULL. Bjarne Stroustrup prefers an unadorned - 0. We prefer NULL because it looks like a - pointer. In fact, some C++ compilers, such as gcc 4.1.0, provide special - definitions of NULL which enable them to give useful - warnings, particularly in situations where sizeof(NULL) - is not equal to sizeof(0). + and NULL (and, for C++11, nullptr). + For projects that allow C++11 features, use nullptr. + For C++03 projects, we prefer NULL because it looks like a + pointer. In fact, some C++ compilers provide special definitions of + NULL which enable them to give useful warnings, + particularly in situations where sizeof(NULL) is not equal + to sizeof(0). +

    Use '\0' for chars. @@ -2545,6 +2594,102 @@ Tashana Landray + +

    + Use auto to avoid type names that are just clutter. + Continue to use manifest type declarations when it helps readability, + and never use auto for anything but local variables. + + + + + In C++11, a variable whose type is given as auto will be given + a type that matches that of the expression used to initialize + it. You can use auto either to initialize a + variable by copying, or to bind a reference. + + vector<string> v; + ... + auto s1 = v[0]; // Makes a copy of v[0]. + const auto& s2 = v[0]; // s2 is a reference to v[0]. + + + +

    + C++ type names can sometimes be long and cumbersome, + especially when they involve templates or namespaces. In a statement like + + sparse_hash_map<string, int>::iterator iter = m.find(val); + + the return type is hard to read, and obscures the primary + purpose of the statement. Changing it to + + auto iter = m.find(val); + + makes it more readable. +

    +

    + Without auto we are sometimes forced to write a + type name twice in the same expression, adding no value + for the reader, as in + + diagnostics::ErrorStatus* status = new diagnostics::ErrorStatus("xyz"); + +

    +

    + Using auto makes it easier to use intermediate + variables when appropriate, by reducing the burden of writing + their types explicitly. +

    +     + +

    Sometimes code is clearer when types are manifest, especially when + a variable's initialization depends on things that were declared + far away. In an expression like + + auto i = x.Lookup(key); + + it may not be obvious what i's type is, if x + was declared hundreds of lines earlier. +

    + +

    Programmers have to understand the difference between auto + and const auto& or they'll get copies when + they didn't mean to. +

    + +

    The interaction between auto and C++11 + brace-initialization can be confusing. (C++11 brace-initialization + isn't an approved feature, but this may become relevant when and + if it is permitted.) The declarations + + auto x(3); // Note: parentheses. + auto y{3}; // Note: curly braces. + + mean different things — x is + an int, while y is + an initializer_list. The same applies to other + normally-invisible proxy types. + +

    + +

    If an auto variable is used as part of an + interface, e.g. as a constant in a header, then a programmer + might change its type while only intending to change its + value, leading to a more radical API change than intended.

    +     + +

    auto is permitted, for local variables only. + Do not use auto for file-scope or namespace-scope + variables, or for class members.

    +

    The auto keyword is also used in an unrelated + C++11 feature: it's part of the syntax for a new kind of + function declaration with a trailing return type. Function + declarations with trailing return types are not permitted.

    +     + +     + Use only approved libraries from the Boost library collection. @@ -2615,11 +2760,15 @@ Tashana Landray + + Use only approved libraries and language extensions from C++11 (formerly known as C++0x). - Currently, none are approved. + + Consider portability to other environments before + using C++11 features in your project. @@ -2639,7 +2788,7 @@ Tashana Landray

    The C++11 standard is substantially more complex than its predecessor (1,300 pages versus 800 pages), and is - unfamilar to many developers. The long-term effects of some + unfamiliar to many developers. The long-term effects of some features on code readability and maintenance are unknown. We cannot predict when its various features will be implemented uniformly by tools that may be of interest (gcc, icc, clang, Eclipse, etc.). @@ -2656,8 +2805,33 @@ Tashana Landray Use only C++11 libraries and language features that have been approved - for use. Currently, no such features are approved. - Features will be approved individually as appropriate. + for use. + Currently only the following C++11 features are approved: +

      +
    • auto (for local variables only).
      • +
    • Use of >> with no intervening space to + close multiple levels of template arguments, as in + set<list<string>>, + where C++03 required a space as in + set<list<string> >. +
      • +
    • Range-based + for loops.
      • +
    • Use of the LL and ULL suffixes on + numeric literals to guarantee that their type is at least 64 bits + wide.
      • +
    • Variadic macros (but note + that use of macros is discouraged).
      • +
    • All of the new STL algorithms in the + <algorithm> + and <numeric> + headers, except for the versions of + min, max, and minmax + whose signatures contain initializer lists.
      • +
    • Use of local types as template parameters.
      • +
    • nullptr and nullptr_t.
      • +
    + Other features will be approved individually as appropriate. Avoid writing code that is incompatible with C++11 (even though it works in C++03). @@ -3097,8 +3271,6 @@ Tashana Landray one may be you!

    - - Use either the // or /* */ syntax, as long @@ -3115,40 +3287,26 @@ Tashana Landray - Start each file with a copyright notice, followed by a - description of the contents of the file. + Start each file with license boilerplate, + followed by a description of its contents. -

    - Every file should contain the following items, in order: -

      -
    • a copyright statement (for example, - Copyright 2008 Google Inc.)
      • -
    • a license boilerplate. Choose the appropriate boilerplate - for the license used by the project (for example, - Apache 2.0, BSD, LGPL, GPL)
      • -
    • an author line to identify the original author of the - file
      • -
    + Every file should contain license boilerplate. + Choose the appropriate boilerplate for the license used by the project + (for example, Apache 2.0, BSD, LGPL, GPL).

    - If you make significant changes to a file that someone else - originally wrote, add yourself to the author line. This can - be very helpful when another - - contributor - has questions about the file and needs to know whom to contact - about it. + If you make significant changes to a file with an author line, + consider deleting the author line.

    - Every file should have a comment at the top, below the copyright - notice and author line, that describes the contents of the file. + Every file should have a comment at the top describing its contents.

    Generally a .h file will describe the classes @@ -3234,7 +3392,7 @@ Tashana Landray

  • If the function allocates memory that the caller must free.
    • -
  • Whether any of the arguments can be NULL. +
  • Whether any of the arguments can be a null pointer.
  • If there are any performance implications of how a function is used. @@ -3318,7 +3476,7 @@ Tashana Landray Each class data member (also called an instance variable or member variable) should have a comment describing what it is used for. If the variable can take sentinel values with - special meanings, such as NULL or -1, document this. + special meanings, such as a null pointer or -1, document this. For example:

    @@ -3396,9 +3554,9 @@ Tashana Landray } - +

    - When you pass in NULL, boolean, or literal integer + When you pass in a null pointer, boolean, or literal integer values to functions, you should consider adding a comment about what they are, or make your code self-documenting by using constants. For example, compare: @@ -3455,13 +3613,11 @@ Tashana Landray

    • - Comments should usually be written as complete - sentences with proper capitalization and periods at the end. - Shorter comments, such as comments at the end of a line of - code, can sometimes be less formal, but you should be - consistent with your style. Complete sentences are more - readable, and they provide some assurance that the comment is - complete and not an unfinished thought. + Comments should be as readable as narrative text, with proper + capitalization and punctuation. In many cases, complete sentences are + more readable than sentence fragments. Shorter comments, such as + comments at the end of a line of code, can sometimes be less formal, but + you should be consistent with your style.

    Although it can be frustrating to have a code reviewer point @@ -3739,23 +3895,6 @@ Tashana Landray

  • Wrapped parameters have a 4 space indent.
    • -

    - If your function is const, the const - keyword should be on the same line as the last parameter: -

    - - // Everything in this function signature fits on a single line - ReturnType FunctionName(Type par) const { - ... - } - - // This function signature requires multiple lines, but - // the const keyword is on the line with the last parameter. - ReturnType ReallyLongFunctionName(Type par1, - Type par2) const { - ... - } -

    If some parameters are unused, comment out the variable name in the function definition: @@ -4349,6 +4488,9 @@ Tashana Landray for ( ; i < 5 ; ++i) { // For loops always have a space after the ... // semicolon, and may have a space before the // semicolon. + for (auto x : counts) { // Range-based for loops always have a + ... // space before and after the colon. + } switch (i) { case 1: // No space before colon in a switch case. ... @@ -4375,7 +4517,8 @@ Tashana Landray // <, or between >( in a cast. vector<char *> x; // Spaces between type and pointer are // okay, but be consistent. - set<list<string> > x; // C++ requires a space in > >. + set<list<string>> x; // Permitted in C++11 code. + set<list<string> > x; // C++03 required a space in > >. set< list<string> > x; // You may optionally use // symmetric spacing in < <. @@ -4565,7 +4708,7 @@ Tashana Landray

    -Revision 3.199 +Revision 3.231

    diff --git a/htmlcssguide.xml b/htmlcssguide.xml index 4ad486c..0687978 100644 --- a/htmlcssguide.xml +++ b/htmlcssguide.xml @@ -3,7 +3,7 @@

    - Revision 2.2 + Revision 2.19

    @@ -13,12 +13,12 @@ This style guide contains many details that are initially hidden from view. They are marked by the triangle icon, which you see here on your left. Click it now. - You should see “Hooray” appear below. + You should see “Hooray” appear below.

    Hooray! Now you know you can expand points to get more - details. Alternatively, there’s a “toggle all” at the + details. Alternatively, there’s a “toggle all” at the top of this document.

    @@ -52,8 +52,8 @@ files are not available over both protocols.

    - Omitting the protocol—which makes the URL - relative—prevents mixed content issues and results in + Omitting the protocol—which makes the URL + relative—prevents mixed content issues and results in minor file size savings.

    @@ -88,7 +88,7 @@

    - Don’t use tabs or mix tabs and spaces for indentation. + Don’t use tabs or mix tabs and spaces for indentation.

    <ul> @@ -162,8 +162,8 @@

    (More on encodings and when and how to specify them can be - found in Character - Sets & Encodings in XHTML, HTML and CSS.) + found in Handling + character encodings in HTML and CSS.)

    @@ -181,7 +181,7 @@ (This item is optional as it is not deemed a realistic expectation to always demand fully documented code. Mileage may vary heavily for HTML and CSS code and depends on the - project’s complexity.) + project’s complexity.)

    @@ -230,7 +230,7 @@ <!DOCTYPE html>.

    - (It’s recommended to use HTML, as text/html. Do not use + (It’s recommended to use HTML, as text/html. Do not use XHTML. XHTML, as application/xhtml+xml, lacks both browser and infrastructure support and offers less room for optimization than HTML.) @@ -252,7 +252,8 @@

    - Use tools such as the W3C + Use tools such as the + W3C HTML validator to test.

    @@ -280,7 +281,7 @@

    - Use elements (sometimes incorrectly called “tags”) for what + Use elements (sometimes incorrectly called “tags”) for what they have been created for. For example, use heading elements for headings, p elements for paragraphs, a elements for anchors, etc. @@ -373,9 +374,9 @@ <link rel="stylesheet" href="grid.css" media="screen"> <link rel="stylesheet" href="print.css" media="print"> <h1 style="font-size: 1em;">HTML sucks</h1> - <p>I’ve read about this on a few sites but now I’m sure: + <p>I’ve read about this on a few sites but now I’m sure: <u>HTML is stupid!!1</u> - <center>I can’t believe there’s no way to control the styling of + <center>I can’t believe there’s no way to control the styling of my website without doing everything all over again!</center> @@ -384,10 +385,10 @@ <title>My first CSS-only redesign</title> <link rel="stylesheet" href="default.css"> <h1>My first CSS-only redesign</h1> - <p>I’ve read about this on a few sites but today I’m actually + <p>I’ve read about this on a few sites but today I’m actually doing it: separating concerns and avoiding anything in the HTML of my website that is presentational. - <p>It’s awesome! + <p>It’s awesome! @@ -406,7 +407,7 @@

    The only exceptions apply to characters with special meaning in HTML (like < and &) as - well as control or “invisible” characters (like no-break + well as control or “invisible” characters (like no-break spaces).

    @@ -415,7 +416,7 @@ <!-- Recommended --> - The currency symbol for the Euro is “€”. + The currency symbol for the Euro is “€”. @@ -432,9 +433,9 @@

    (This approach may require a grace period to be established - as a wider guideline as it’s significantly different + as a wider guideline as it’s significantly different from what web developers are typically taught. For - consistency and simplicity reasons it’s best served + consistency and simplicity reasons it’s best served omitting all optional tags, not just a selection.)

    @@ -516,7 +517,7 @@

    (If you run into issues around whitespace between list items - it’s acceptable to put all li elements in one + it’s acceptable to put all li elements in one line. A linter is encouraged to throw a warning instead of an error.)

    @@ -548,12 +549,12 @@ - Use double quotation marks for attribute values where necessary. + When quoting attributes values, use double quotation marks.

    - When quoting attribute values, use double ("") rather - than single quotation marks (''). + Use double ("") rather than single quotation marks + ('') around attribute values.

    <!-- Not recommended --> @@ -580,8 +581,8 @@

    Use tools such as the - W3C CSS validator to - test. + W3C + CSS validator to test.

    Using valid CSS is a measurable baseline quality attribute @@ -608,7 +609,7 @@

    Generic names are simply a fallback for elements that have no particular or no meaning different from their siblings. They are - typically needed as “helpers.” + typically needed as “helpers.”

    Using functional or generic names reduces the probability of @@ -723,7 +724,7 @@

    - Omit unit specification after “0” values. + Omit unit specification after “0” values.

    @@ -738,7 +739,7 @@

    - Omit leading “0”s in values. + Omit leading “0”s in values.

    @@ -804,7 +805,7 @@ in order to improve understanding and scannability.

    - /* Not recommended: does not separate the words “demo” and “image” */ + /* Not recommended: does not separate the words “demo” and “image” */ .demoimage {} /* Not recommended: uses underscore instead of hyphen */ @@ -819,12 +820,12 @@     - Avoid user agent detection as well as CSS “hacks”—try a different + Avoid user agent detection as well as CSS “hacks”—try a different approach first.

    - It’s tempting to address styling differences over user + It’s tempting to address styling differences over user agent detection or special CSS filters, workarounds, and hacks. Both approaches should be considered last resort in order to achieve and maintain an efficient and manageable @@ -832,7 +833,7 @@ free pass will hurt projects in the long run as projects tend to take the way of least resistance. That is, allowing and making it easy to use detection and hacks means using - detection and hacks more frequently—and more frequently + detection and hacks more frequently—and more frequently is too frequently.

    @@ -918,7 +919,7 @@     - Use a space after a property name’s colon. + Use a space after a property name’s colon.

    @@ -986,14 +987,18 @@

    - Use single quotation marks for attribute selectors and property values - where necessary. + Use single quotation marks for attribute selectors and property values.

    - When quoting attribute selectors and property values, use single - ('') rather than double ("") quotation - marks. Do not use quotation marks in URI values (url()). + Use single ('') rather than double ("") + quotation marks for attribute selectors or property values. Do not + use quotation marks in URI values (url()). +

    +

    + Exception: If you do need to use the @charset rule, + use double quotation marks—single + quotation marks are not permitted.

    /* Not recommended */ @@ -1048,7 +1053,7 @@ Be consistent.

    - If you’re editing code, take a few minutes to look at the code + If you’re editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your @@ -1056,8 +1061,8 @@

    The point of having style guidelines is to have a common vocabulary - of coding so people can concentrate on what you’re saying rather - than on how you’re saying it. We present global style rules here so + of coding so people can concentrate on what you’re saying rather + than on how you’re saying it. We present global style rules here so people know the vocabulary, but local style is also important. If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to @@ -1066,7 +1071,7 @@

    - Revision 2.2 + Revision 2.19

    diff --git a/javascriptguide.xml b/javascriptguide.xml index 1df49a0..32e9e63 100644 --- a/javascriptguide.xml +++ b/javascriptguide.xml @@ -3,7 +3,7 @@

    - Revision 2.28 + Revision 2.64

    @@ -44,6 +44,8 @@ + + @@ -69,37 +71,90 @@ - >Use NAMES_LIKE_THIS for constants. - Use @const where appropriate. - Never use the const keyword. +
      +
    • Use NAMES_LIKE_THIS for constant values.
      • +
    • Use @const to indicate a constant (non-overwritable) + pointer (a variable or property).
      • +
    • Never use the + + const keyword + as it not supported in Internet Explorer.
      • +
    -

    For simple primitive value constants, the naming convention is - enough.

    - - /** - * The number of seconds in a minute. - * @type {number} - */ - goog.example.SECONDS_IN_A_MINUTE = 60; - -

    For non-primitives, use the @const annotation.

    - - /** - * The number of seconds in each of the given units. - * @type {Object.<number>} - * @const - */ - goog.example.SECONDS_TABLE = { - minute: 60, - hour: 60 * 60 - day: 60 * 60 * 24 - } - -

    This allows the compiler to enforce constant-ness.

    -

    As for the const keyword, Internet Explorer doesn't - parse it, so don't use it.

    + + +

    If a value is intended to be constant + and immutable, it should be given a name + in CONSTANT_VALUE_CASE. + ALL_CAPS additionally implies @const + (that the value is not overwritable). +

    + +

    Primitive types (number, string, + boolean) are constant values.

    + +

    Objects' + immutabilty is more subjective — objects should be + considered immutable only if they do not demonstrate obeserverable + state change. This is not enforced by the compiler.

    + + +     + + +

    The @const annotation on a variable or property + implies that it is not overwritable. This is enforced by the + compiler at build time. This behavior is consistent with the + + const keyword (which we do not use due to the + lack of support in Internet Explorer).

    + +

    A @const annotation on a method additionally + implies that the method should not be overriden in subclasses.

    +     + + + +

    Note that @const does not necessarily imply + CONSTANT_VALUES_CASE. + + However, CONSTANT_VALUES_CASE + does imply @const. +

    + + + /** + * Request timeout in milliseconds. + * @type {number} + */ + goog.example.TIMEOUT_IN_MILLISECONDS = 60; + + +

    The number of seconds in a minute never changes. It is a + constant value. ALL_CAPS + also implies @const, so the constant cannot be + overwritten. +

    + +

    The open source compiler will allow the symbol it to be + overwritten because the constant is + not marked as @const.

    + + + /** + * Map of URL to response string. + * @const + */ + MyClass.fetchedUrlCache_ = new goog.structs.Map(); + + +

    In this case, the pointer can never be overwritten, but + value is highly mutable and not constant (and thus in + camelCase, not ALL_CAPS).

    +     +     @@ -163,6 +218,20 @@

    This has really surprised people, so make sure your assignments end with semicolons.

    + +

    Semicolons should be included at the end of function expressions, + but not at the end of function declarations. The distinction is + best illustrated with an example:

    + + var foo = function() { + return true; + }; // semicolon here. + + function foo() { + return true; + } // no semicolon here. + +     @@ -289,16 +358,58 @@ - - Foo.prototype.bar = function() { ... }; + + /** @constructor */ + function SomeConstructor() { + this.someProperty = 1; + } + Foo.prototype.someMethod = function() { ... }; -

    While there are several methods for attaching methods and - properties to a constructor, the preferred style is:

    +

    While there are several ways to attach methods and properties to an + object created via "new", the preferred style for methods + is:

    Foo.prototype.bar = function() { /* ... */ }; +

    The preferred style for other properties is to initialize the field + in the constructor:

    + + /** @constructor */ + function Foo() { + this.bar = value; + } + + +

    Current JavaScript engines optimize based on the "shape" + of an object, + adding a property to an object (including overriding + a value set on the prototype) changes the shape and can degrade + performance.

    +     + +     + + + Prefer this.foo = null. + + + Foo.prototype.dispose = function() { + this.property_ = null; + }; + +

    Instead of:

    + + Foo.prototype.dispose = function() { + delete this.property_; + }; + +

    In modern JavaScript engines, changing the number of properties on an + object is much slower than reassigning the values. The delete keyword + should be avoided except when it is necessary to remove a property + from an object's iterated list of keys, or to change the result of + if (key in obj).

     @@ -604,10 +715,16 @@ -

    In general, use functionNamesLikeThis, - variableNamesLikeThis, ClassNamesLikeThis, - EnumNamesLikeThis, methodNamesLikeThis, - and SYMBOLIC_CONSTANTS_LIKE_THIS.

    +

    In general, use + functionNamesLikeThis, + variableNamesLikeThis, + ClassNamesLikeThis, + EnumNamesLikeThis, + methodNamesLikeThis, + CONSTANT_VALUES_LIKE_THIS, + foo.namespaceNamesLikeThis.bar, and + filenameslikethis.js. +

    @@ -622,8 +739,12 @@

    For more information on private and protected, read the section on - visibility - .

    + visibility. +

    + + + +     @@ -719,7 +840,7 @@ /** * WRONG -- Do NOT do this. * @constructor - * @extend {foo.hats.RoundHat} + * @extends {foo.hats.RoundHat} */ foo.hats.BowlerHat = function() { }; @@ -736,7 +857,7 @@ /** * @constructor - * @extend {foo.hats.RoundHat} + * @extends {foo.hats.RoundHat} */ googleyhats.BowlerHat = function() { ... @@ -1005,6 +1126,55 @@ }); + +

    + goog.scope + may be used to shorten references to + namespaced symbols in programs using + the Closure + Library.

    +

    Only one goog.scope invocation may be added per + file. Always place it in the global scope.

    +

    The opening goog.scope(function() { invocation + must be preceded by exactly one blank line and follow any + goog.provide statements, goog.require + statements, or top-level comments. The invocation must be closed on + the last line in the file. Append // goog.scope to the + closing statement of the scope. Separate the comment from the + semicolon by two spaces.

    +

    Similar to C++ namespaces, do not indent under goog.scope + declarations. Instead, continue from the 0 column.

    +

    Only alias names that will not be re-assigned to another object + (e.g., most constructors, enums, and namespaces). Do not do + this:

    + + + goog.scope(function() { + var Button = goog.ui.Button; + + Button = function() { ... }; + ... + + +

    Names must be the same as the last property of the global that they + are aliasing.

    + + + goog.provide('my.module'); + + goog.require('goog.dom'); + goog.require('goog.ui.Button'); + + goog.scope(function() { + var Button = goog.ui.Button; + var dom = goog.dom; + var module = my.module; + + module.button = new Button(dom.$('my-button')); + ... + }); // goog.scope + +

    In fact, except for @@ -1069,6 +1239,12 @@ moreComplicatedB : moreComplicatedC; +

    This includes the dot operator.

    + + var x = foo.bar(). + doSomething(). + doSomethingElse(); +     @@ -1081,7 +1257,8 @@

    Never use parentheses for unary operators such as delete, typeof and void or after keywords such as return, throw as - well as others (case, in or new).

    + well as others (case, in or + new).

     @@ -1153,20 +1330,25 @@ // File 1. /** @constructor */ - AA_PublicClass = function() { + AA_PublicClass = function() { + /** @private */ + this.privateProp_ = 2; + + /** @protected */ + this.protectedProp = 4; }; /** @private */ AA_PublicClass.staticPrivateProp_ = 1; - /** @private */ - AA_PublicClass.prototype.privateProp_ = 2; - /** @protected */ AA_PublicClass.staticProtectedProp = 31; + /** @private */ + AA_PublicClass.prototype.privateMethod_ = function() {}; + /** @protected */ - AA_PublicClass.prototype.protectedProp = 4; + AA_PublicClass.prototype.protectedMethod = function() {}; // File 2. @@ -1210,18 +1392,17 @@ Encouraged and enforced by the compiler. +

    When documenting a type in JSDoc, be as specific and accurate as - possible. The types we support are + possible. The types we support are based on the - JS2 - - style types and JS1.x types.

    + EcmaScript 4 spec.

    -

    The JS2 proposal contained a language for specifying JavaScript +

    The ES4 proposal contained a language for specifying JavaScript types. We use this language in JsDoc to express the types of function parameters and return values.

    -

    As the JS2 proposal has evolved, this language has changed. The +

    As the ES4 proposal has evolved, this language has changed. The compiler still supports old syntaxes for types, but those syntaxes are deprecated.

    @@ -1229,7 +1410,7 @@ - + @@ -1237,15 +1418,63 @@ - + + + + + + + + + + + + + - - + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - + - + @@ -1786,12 +2023,10 @@

    In cases where type-checking doesn't accurately infer the type of an expression, it is possible to add a type cast comment by adding a type annotation comment and enclosing the expression in - parentheses. The parentheses are required, and may surround the type - annotation comment as well.

    + parentheses. The parentheses are required.

    /** @type {number} */ (x) - (/** @type {number} */ x) @@ -1802,10 +2037,8 @@ nullable, and undefined function parameters and class properties.

    -

    Object types (also known as reference types) are nullable by - default. NOTE: Function types are not nullable by default. An - object is defined as anything except a string, number, boolean, - undefined, or null. For example, the following declaration

    +

    Instances of classes and interfaces are nullable by default. + For example, the following declaration

    /** @@ -1970,7 +2203,8 @@

    All files, classes, methods and properties should be documented with JSDoc - comments.

    + comments with the appropriate tags + and types.

    Inline comments should be of the // variety.

    @@ -2074,19 +2308,16 @@

    + A copyright notice and author information are optional. The top level comment is designed to orient readers unfamiliar with the code to what is in this file. - It should provide a description of the file's contents, its - author(s), and any dependencies or compatibility information. As an - example:

    + It should provide a description of the file's contents and any + dependencies or compatibility information. As an example:

    - // Copyright 2009 Google Inc. All Rights Reserved. - /** * @fileoverview Description of file, its uses and information * about its dependencies. - * @author user@google.com (Firstname Lastname) */ @@ -2094,8 +2325,9 @@     -

    Classes must be documented with a description, and appropriate - type tags. +

    Classes must be documented with a description and a + type tag that + identifies the constructor.

    @@ -2114,9 +2346,10 @@     -

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

    +

    Parameter and return types should be documented. The method + description may be omitted if it is obvious from the parameter + or return type descriptions. Method descriptions should start + with a sentence written in the third person declarative voice.

    /** * Operates on an instance of MyClass and returns something. @@ -2128,22 +2361,23 @@ // ... } - -

    For simple getters that take no parameters and have no - side effects, the description can be omitted.

     - /** - * Maximum number of things per pane. - * @type {number} - */ - project.MyClass.prototype.someProperty = 4; + /** @constructor */ + project.MyClass = function() { + /** + * Maximum number of things per pane. + * @type {number} + */ + this.someProperty = 4; + } +

    Operator NameSyntax Name Syntax Description Deprecated Syntaxes
    Type NamePrimitive Type - {boolean}, {Window}, - {goog.ui.Menu} + There are 5 primitive types in JavaScript: + {null}, + {undefined}, + {boolean}, + {number}, and + {string}. Simply the name of a type.
    Instance Type + {Object}
    + An instance of Object or null.

    + {Function}
    + An instance of Function or null.

    + {EventTarget}
    + An instance of a constructor that implements the EventTarget + interface, or null. +

    		An instance of a constructor or interface function.

    + + Constructor functions are functions defined with the + @constructor JSDoc tag. + Interface functions are functions defined with the + @interface JSDoc tag.

    + + By default, instance types will accept null. This is the only + type syntax that makes the type nullable. Other type syntaxes + in this table will not accept null. +

    		+
    Enum Type + {goog.events.EventType}
    + One of the properties of the object literal initializer + of goog.events.EventType. +     		An enum must be initialized as an object literal, or as + an alias of another enum, annotated with the @enum + JSDoc tag. The properties of this literal are the instances + of the enum. The syntax of the enum is defined + below.

    + + Note that this is one of the few things in our type system + that were not in the ES4 spec. +

    		+
    Type Application @@ -1254,7 +1483,7 @@
    An object in which the keys are strings and the values are numbers.     		Patameterizes a type, by applying a set of type arguments + Parameterizes a type, by applying a set of type arguments to that type. The idea is analogous to generics in Java. @@ -1265,14 +1494,47 @@ {(number|boolean)}
    A number or a boolean.     		Indicates that a value might have type A OR type B.Indicates that a value might have type A OR type B.

    + + The parentheses may be omitted at the top-level + expression, but the parentheses should be included in + sub-expressions to avoid ambiguity.
    + {number|boolean}
    + {function(): (number|boolean)} +

    		- {(number,boolean)}, - {number|boolean}, + {(number,boolean)},
    {(number||boolean)}
    Nullable type + {?number}
    A number or null. +     		Shorthand for the union of the null type with any + other type. This is just syntactic sugar. + + {number?} +
    Non-nullable type + {!Object}
    An Object, but never the + null value. +     		Filters null out of nullable types. Most often used + with instance types, which are nullable by default. + + {Object!} +
    Record Type @@ -1292,35 +1554,6 @@
    Nullable type - {?number}
    A number or NULL. -     		Indicates that a value is type A or null. - By default, all object types are nullable. - NOTE: Function types are not nullable. - - {number?} -
    Non-nullable type - {!Object}
    An Object, but never the - null value. -     		Indicates that a value is type A and not null. By default, - all value types (boolean, number, string, and undefined) are - not nullable. - - {Object!} -
    Function Type @@ -1393,7 +1626,7 @@
    Function optional argumentsFunction optional arguments {function(?string=, number=)}
    A function that takes one optional, nullable string and one @@ -1407,7 +1640,7 @@
    - Function optional arguments + Function optional arguments (in @param annotations) @@ -1660,7 +1893,7 @@ An Object in which the keys are numbers and the values are strings.

    Note that in JavaScript, the keys are always - implicitly coverted to strings, so + implicitly converted to strings, so obj['1'] == obj[1]. So the key wil always be a string in for...in loops. But the compiler will verify the type if the key when indexing into @@ -1741,12 +1974,16 @@ /** @enum {string} */ project.MyEnum = { + /** The color blue. */ BLUE: '#0000dd', + /** The color red. */ RED: '#dd0000' };

    		EnumerationEnumeration

    + JSDoc comments on enum values are optional. +

    @@ -2217,21 +2451,37 @@ mynamespace.MY_BEER = 'stout'; /** @const */ MyClass.MY_BEER = 'stout'; + + /** + * Initializes the request. + * @const + */ + mynamespace.Request.prototype.initialize = function() { + // This method cannot be overriden in a subclass. + } @@ -2303,6 +2553,34 @@ + + + + + + + + + + + + @@ -2446,8 +2751,9 @@ @@ -2464,13 +2770,13 @@ @@ -2546,11 +2852,12 @@ @@ -2646,7 +2953,8 @@ Used with method, function and constructor calls to document the arguments of a function.

    - Type names must be enclosed in curly braces. If the type + Type + names must be enclosed in curly braces. If the type is omitted, the compiler will not type-check the parameter. @@ -2721,7 +3029,8 @@ component is visible, false otherwise". If there is no return value, do not use an @return tag.

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

    + + + + + + @@ -2852,7 +3195,8 @@ @@ -2920,25 +3264,48 @@ - + - Should be defined in the same file as the top level class. + Only provide top-level symbols. - Inner classes and enums defined on another class should be defined in - the same file as the top level class. goog.provide - statements are only necessary for the top level class. +

    + All members defined on a class should be in the same file. So, only + top-level classes should be provided in a file that contains multiple + members defined on the same class (e.g. enums, inner classes, etc). +

    +

    Do this:

    + + goog.provide('namespace.MyClass'); + +

    Not this:

    + + goog.provide('namespace.MyClass'); + goog.provide('namespace.MyClass.Enum'); + goog.provide('namespace.MyClass.InnerClass'); + goog.provide('namespace.MyClass.TypeDef'); + goog.provide('namespace.MyClass.CONSTANT'); + goog.provide('namespace.MyClass.staticMethod'); + +

    + Members on namespaces may also be provided: +

    + + goog.provide('foo.bar'); + goog.provide('foo.bar.method'); + goog.provide('foo.bar.CONSTANT'); +     - Encouraged + Required

    Use of JS compilers such as the Closure Compiler - is encouraged.

    + is required for all customer-facing code.

    @@ -3096,40 +3463,6 @@ - -

    It is common to see this:

    - - function listHtml(items) { - var html = '<div class="foo">'; - for (var i = 0; i < items.length; ++i) { - if (i > 0) { - html += ', '; - } - html += itemHtml(items[i]); - } - html += '</div>'; - return html; - } - - -

    but this is slow in Internet Explorer, so it is better to do - this:

    - - function listHtml(items) { - var html = []; - for (var i = 0; i < items.length; ++i) { - html[i] = itemHtml(items[i]); - } - return '<div class="foo">' + html.join(', ') + '</div>'; - } - - -

    You can also use an array as a stringbuilder, and convert it into - a string with myArray.join(''). Note that since - assigning values to an array is faster than using - push() you should use assignment where possible.

    -     -

    Node lists are often implemented as node iterators with a filter. This means that getting a property like length is O(n), and @@ -3194,7 +3527,7 @@

    - Revision 2.28 + Revision 2.64

    diff --git a/objcguide.xml b/objcguide.xml index 06abacf..6c37a79 100644 --- a/objcguide.xml +++ b/objcguide.xml @@ -4,7 +4,7 @@

    -Revision 2.36 +Revision 2.48

    @@ -129,13 +129,6 @@ Revision 2.36

    - // Foo.h - // AwesomeProject - // - // Created by Greg Miller on 6/13/08. - // Copyright 2008 Google, Inc. All rights reserved. - // - #import <Foundation/Foundation.h> // A sample class demonstrating good Objective-C style. All interfaces, @@ -146,8 +139,8 @@ Revision 2.36 // (no blank line between this comment and the interface) @interface Foo : NSObject { @private - NSString *bar_; - NSString *bam_; + NSString *_bar; + NSString *_bam; } // Returns an autoreleased instance of Foo. See -initWithBar: for details @@ -158,7 +151,7 @@ Revision 2.36 // does a thing. - (id)initWithBar:(NSString *)bar; - // Gets and sets |bar_|. + // Gets and sets |_bar|. - (NSString *)bar; - (void)setBar:(NSString *)bar; @@ -177,14 +170,6 @@ Revision 2.36

    - // - // Foo.m - // AwesomeProject - // - // Created by Greg Miller on 6/13/08. - // Copyright 2008 Google, Inc. All rights reserved. - // - #import "Foo.h" @@ -201,25 +186,25 @@ Revision 2.36 - (id)initWithBar:(NSString *)bar { if ((self = [super init])) { - bar_ = [bar copy]; - bam_ = [[NSString alloc] initWithFormat:@"hi %d", 3]; + _bar = [bar copy]; + _bam = [[NSString alloc] initWithFormat:@"hi %d", 3]; } return self; } - (void)dealloc { - [bar_ release]; - [bam_ release]; + [_bar release]; + [_bam release]; [super dealloc]; } - (NSString *)bar { - return bar_; + return _bar; } - (void)setBar:(NSString *)bar { - [bar_ autorelease]; - bar_ = [bar copy]; + [_bar autorelease]; + _bar = [bar copy]; } - (BOOL)doWorkWithBlah:(NSString *)blah { @@ -321,13 +306,13 @@ Revision 2.36

    When the first keyword is shorter than the others, indent the later - lines by at least four spaces. You can do this by making keywords - line up vertically, not aligning colons: + lines by at least four spaces, maintaining colon alignment:

    - (void)short:(GTMFoo *)theFoo - longKeyword:(NSRect)theRect - evenLongerKeyword:(float)theInterval { + longKeyword:(NSRect)theRect + evenLongerKeyword:(float)theInterval + error:(NSError **)theError { ... } @@ -371,15 +356,15 @@ Revision 2.36

    - As with declarations and definitions, when the keyword lengths make - it impossible to align colons and still have four leading - spaces, indent later lines by four spaces and align keywords after the - first one, instead of aligning the colons. + As with declarations and definitions, when the first keyword is shorter + than the others, indent the later lines by at least four spaces, + maintaining colon alignment:

    [myObj short:arg1 - longKeyword:arg2 - evenLongerKeyword:arg3]; + longKeyword:arg2 + evenLongerKeyword:arg3 + error:arg4];     @@ -446,7 +431,7 @@ Revision 2.36 @interface MyProtocoledClass : NSObject<NSWindowDelegate> { @private - id<MyFancyDelegate> delegate_; + id<MyFancyDelegate> _delegate; } - (void)setDelegate:(id<MyFancyDelegate>)aDelegate; @end @@ -500,7 +485,7 @@ Revision 2.36 // Using a block with a C API follows the same alignment and spacing // rules as with Objective-C. - dispatch_async(fileIOQueue_, ^{ + dispatch_async(_fileIOQueue, ^{ NSString* path = [self sessionFilePath]; if (path) { // ... @@ -535,7 +520,7 @@ Revision 2.36 void (^largeBlock)(void) = ^{ // ... }; - [operationQueue_ addOperationWithBlock:largeBlock]; + [_operationQueue addOperationWithBlock:largeBlock];     @@ -579,7 +564,7 @@ Revision 2.36 File names should reflect the name of the class implementation that - they contain -- including case. Follow the convention that your + they contain—including case. Follow the convention that your project uses. @@ -648,16 +633,16 @@ Revision 2.36 // A typical Objective-C class, using Objective-C naming. @interface MyDelegate : NSObject { @private - int instanceVar_; - CrossPlatformAPI* backEndObject_; + int _instanceVar; + CrossPlatformAPI* _backEndObject; } - (void)respondToSomething:(id)something; @end @implementation MyDelegate - (void)respondToSomething:(id)something { // bridge from Cocoa through our C++ backend - instanceVar_ = backEndObject->DoSomethingPlatformSpecific(); - NSString* tempString = [NSString stringWithInt:instanceVar_]; + _instanceVar = _backEndObject->DoSomethingPlatformSpecific(); + NSString* tempString = [NSString stringWithInt:_instanceVar]; NSLog(@"%@", tempString); } @end @@ -752,11 +737,8 @@ Revision 2.36 Variables names start with a lowercase and use mixed case to delimit - words. Class member variables have trailing underscores. For example: - myLocalVariable, myInstanceVariable_. Members - used for KVO/KVC bindings may begin with a leading underscore - iff use of Objective-C 2.0's @property isn't - allowed. + words. Instance variables have leading underscores. For example: + myLocalVariable, _myInstanceVariable. @@ -786,15 +768,13 @@ Revision 2.36

    - Instance variables are mixed case and should be suffixed with a - trailing underscore, e.g. usernameTextField_. However, - we permit an exception when binding to a member variable using - KVO/KVC and Objective-C 2.0 cannot be used (due to OS release - constraints). In this case, it is acceptable to prefix the variable - with an underscore, per Apple's accepted practices for key/value - naming. If Objective-C 2.0 can be used, @property and - @synthesize provide a solution that conforms to the - naming guidelines. + Instance variables are mixed case and should be prefixed with an + underscore e.g. _usernameTextField. Note that historically + the convention was to put the underscore at the end of the name, and + projects may opt to continue using trailing underscores in new code + in order to maintain consistency within their codebase (see the + Historical Notes section). It is recommended you leave old + code as-is, unless doing so would create inconsistency within a class.

    @@ -825,7 +805,7 @@ Revision 2.36 When writing your comments, write for your audience: the next contributor - who will need to understand your code. Be generous — the next + who will need to understand your code. Be generous—the next one may be you!

    @@ -835,36 +815,24 @@ Revision 2.36

    - Start each file with a basic description of the contents of the file, - followed by an author, and then followed by a copyright notice and/or - license boilerplate. + A file may optionally start with a description of its contents. - - - -

    - Every file should contain the following items, in order: -

      -
    • a basic description of the contents of the file
      • -
    • an author line
      • -
    • a copyright statement (for example, - Copyright 2008 Google Inc.)
      • -
    • license boilerplate if neccessary. Choose the appropriate - boilerplate for the license used by the project (e.g. - Apache 2.0, BSD, LGPL, GPL)
      • -
    -

    -

    - If you make significant changes to a file that someone else - originally wrote, add yourself to the author line. This can - be very helpful when another - - contributor - has questions about the file and needs to know whom to contact - about it. -

    -     + +

    + Every file should contain the following items, in order: +

      +
    • license boilerplate if neccessary. Choose the appropriate + boilerplate for the license used by the project (e.g. + Apache 2.0, BSD, LGPL, GPL).
      • +
    • a basic description of the contents of the file if necessary.
      • +
    +

    +

    + If you make significant changes to a file with an author line, + consider deleting the author line since revision history already + provides a more detailed and accurate record of authorship. +

    @@ -932,48 +900,57 @@ Revision 2.36 outside the most common Objective-C usage idioms.     -

    - Instance variables which are pointers to objects derived from NSObject - are presumed to be retained, and should be either commented as weak or - declared with the __weak lifetime qualifier when applicable. - Similarly, declared properties must specify a weak or - assign property attribute if they are not retained by the - class. An exception is instance variables labeled as IBOutlets in Mac - software, which are presumed to not be retained. -

    -

    - Where instance variables are pointers to CoreFoundation, C++, and - other non-Objective-C objects, they should always be declared with - the __strong and __weak type modifiers to indicate which pointers are - and are not retained. CoreFoundation and other non-Objective-C object - pointers require explicit memory management, even when building for - automatic reference counting or garbage collection. When the __weak - type modifier is not allowed (e.g. C++ member variables when compiled - under clang), a comment should be used instead. -

    -

    - Be mindful that support for automatic C++ objects encapsulated in - Objective-C objects is disabled by default, as described here. -

    -

    - Examples of strong and weak declarations: - - @interface MyDelegate : NSObject { - @private - IBOutlet NSButton *okButton_; // normal NSControl; implicitly weak on Mac only + +

    + Instance variables which are pointers to objects derived from NSObject + are presumed to be retained, and should be either commented as weak or + declared with the __weak lifetime qualifier when applicable. + Similarly, declared properties must specify an assign property + attribute if they are not retained by the class. An exception is + instance variables labeled as IBOutlets in desktop Mac software, + which are presumed to not be retained. +

    +

    + Where instance variables are pointers to Core Foundation, C++, and + other non-Objective-C objects, they should always be declared with + the __strong or __weak type modifiers to indicate which pointers are + and are not retained. Core Foundation and other non-Objective-C object + pointers require explicit memory management, even when building for + automatic reference counting or garbage collection. When the __weak + type modifier is not allowed (e.g. C++ member variables when compiled + under clang), a comment should be used instead. +

    +

    + Be mindful that support for automatic C++ objects encapsulated in + Objective-C objects is disabled by default, as described + here. +

    +

    + Examples of strong and weak declarations: + + @interface MyDelegate : NSObject { + @private + IBOutlet NSButton *_okButton; // normal NSControl; implicitly weak on Mac only - AnObjcObject* doohickey_; // my doohickey - __weak MyObjcParent *parent_; // so we can send msgs back (owns me) + AnObjcObject* _doohickey; // my doohickey + __weak MyObjcParent *_parent; // so we can send msgs back (owns me) - // non-NSObject pointers... - __strong CWackyCPPClass *wacky_; // some cross-platform object - __strong CFDictionaryRef *dict_; - } - @property(strong, nonatomic) NSString *doohickey; - @property(weak, nonatomic) NSString *parent; - @end - -

    + // non-NSObject pointers... + __strong CWackyCPPClass *_wacky; // some cross-platform object + __strong CFDictionaryRef *_dict; + } + @property(strong, nonatomic) NSString *doohickey; + @property(weak, nonatomic) NSString *parent; + @end + +

    + + +

    + Object ownership and lifetime are explicit when using ARC, so no + additional comments are required. +

    +     @@ -981,15 +958,16 @@ Revision 2.36 - + - Member variables should be declared @private. + Instance variables should be marked @private when they are + declared in a header file. @interface MyClass : NSObject { @private - id myInstanceVariable_; + id _myInstanceVariable; } // public accessors, setter takes ownership - (id)myInstanceVariable; @@ -1083,7 +1061,7 @@ Revision 2.36

    Unlike C++, Objective-C doesn't have a way to differentiate between - public and private methods — everything is public. As a result, + public and private methods—everything is public. As a result, avoid placing methods in the public API unless they are actually expected to be used by a consumer of the class. This helps reduce the likelihood they'll be called when you're not expecting it. This includes @@ -1092,7 +1070,6 @@ Revision 2.36 file as opposed to adding them to the public header.

    - // GTMFoo.m #import "GTMFoo.h" @interface GTMFoo (PrivateDelegateHandling) @@ -1263,8 +1240,8 @@ Revision 2.36

    - (void)setFoo:(GMFoo *)aFoo { - [foo_ autorelease]; // Won't dealloc if |foo_| == |aFoo| - foo_ = [aFoo retain]; + [_foo autorelease]; // Won't dealloc if |_foo| == |aFoo| + _foo = [aFoo retain]; } @@ -1288,13 +1265,13 @@ Revision 2.36 - (id)init { self = [super init]; if (self) { - bar_ = [[NSMutableString alloc] init]; // good + _bar = [[NSMutableString alloc] init]; // good } return self; } - (void)dealloc { - [bar_ release]; // good + [_bar release]; // good [super dealloc]; }     @@ -1352,8 +1329,8 @@ Revision 2.36

    - (void)setFoo:(NSString *)aFoo { - [foo_ autorelease]; - foo_ = [aFoo copy]; + [_foo autorelease]; + _foo = [aFoo copy]; } @@ -1444,7 +1421,7 @@ Revision 2.36 handled by the Objective-C runtime. If the method has no return result, you're good to go. However if there is one, there may be differences based on runtime architecture, return size, and OS X - version (see Apple's + version (see Apple's documentation for specifics).

    @@ -1463,16 +1440,16 @@ Revision 2.36

    - BOOL is defined as an unsigned char in Objective-C which - means that it can have values other than YES (1) and + BOOL is defined as a signed char in Objective-C which means + that it can have values other than YES (1) and NO (0). Do not cast or convert general integral values directly to BOOL. Common mistakes include casting or converting an array's size, a pointer value, or the result of a bitwise logic operation to a BOOL which, depending on the value of the last byte of the integral result, could still result in a NO value. When converting a general integral value to a - BOOL use ternery operators to return a YES - or NO value. + BOOL use ternery operators to return a YES or + NO value.

    You can safely interchange and convert BOOL, @@ -1529,58 +1506,54 @@ Revision 2.36

    - Properties in general are allowed with the following caveat: properties - are an Objective-C 2.0 feature which will limit your code to running - on the iPhone and Mac OS X 10.5 (Leopard) and higher. Dot notation + Use of the @property directive is preferred, with the following caveat: + properties are an Objective-C 2.0 feature which will limit your code to + running on the iPhone and Mac OS X 10.5 (Leopard) and higher. Dot notation is allowed only for access to a declared @property.

    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 _. The optional - space between the @property and the opening parenthesis + leading _ requirement. The property's name should be the same as its + associated instance variable without the leading _. 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. -

    - @interface MyClass : NSObject { - @private - NSString *name_; - } + @interface MyClass : NSObject @property(copy, nonatomic) NSString *name; @end @implementation MyClass - @synthesize name = name_; + // No code required for auto-synthesis, else use: + // @synthesize name = _name; @end

    A property's declaration must come immediately after the instance - variable block of a class interface. A property's definition must - come immediately after the @implementation block in a - class definition. They are indented at the same level as the - @interface or @implementation statements - that they are enclosed in. + variable block of a class interface. A property's definition (if + not using automatic synthesis) must come immediately after the + @implementation block in a class definition. They are + indented at the same level as the @interface or + @implementation statements that they are enclosed in.

    @interface MyClass : NSObject { @private - NSString *name_; + NSString *_name; } @property(copy, nonatomic) NSString *name; @end @implementation MyClass - @synthesize name = name_; + @synthesize name = _name; + - (id)init { - ... + ... } @end @@ -1649,19 +1622,20 @@ Revision 2.36

    - For code that will run on iOS only, use of automatically synthesized - instance variables is preferred. -

    -

    - When synthesizing the instance variable, use - @synthesize var = var_; as this prevents accidentally calling - var = blah; when self.var = blah; is intended. + Use of automatically synthesized instance variables is preferred. Code + that must support earlier versions of the compiler toolchain (Xcode 4.3 + or earlier or when compiling with GCC) or is using properties inherited + from a protocol should prefer the @synthesize directive.

    // Header file - @interface Foo : NSObject + @protocol Thingy + @property(nonatomic, copy) NSString *widgetName; + @end + + @interface Foo : NSObject<Thingy> // A guy walks into a bar. @property(nonatomic, copy) NSString *bar; @end @@ -1672,10 +1646,89 @@ Revision 2.36 @end @implementation Foo - @synthesize bar = bar_; - @synthesize baz = baz_; + @synthesize widgetName = _widgetName; @end + +

    + Automatically synthesized instance variables take the form of the + property's name prefixed with an underscore and so typically conform to + the required variable naming style. If your property name is unusual, + or you are otherwise unable to use automatically synthesized instance + variables, use of the @synthesize directive is preferred, with the + instance variable name specified explicitly (as @synthesize does not add + a leading underscore by default). +

    + +     + + + +

    + For projects that use Xcode 4.2 or later and will run only on 64-bit + Mac OS X 10.7 and iOS 5.0 and later, ARC is preferred. Use manual + reference counting when supporting earlier environments where zeroing + weak pointers are not available. +

    +

    + Classes that require ARC should include a preprocessor directive to + prevent compilation using manual reference counting. +

    +

    + Ownership qualifiers like __unsafe_unretained and + __weak should precede variable names. Specifying + __strong for variables is not required since it is + the default. Properties, on the other hand, should always specify the + strong keyword rather than relying on the compiler default. +

    +     + +

    + Example of an implementation file enforcing ARC style. Note that + declaring instance variables in the @implementation is permitted when + using ARC. + + #if !defined(__has_feature) || !__has_feature(objc_arc) + #error "This file requires ARC support." + #endif + + #import "Foo.h" + + @implementation Foo { + @private + Bar * __weak _bar; + Baz * __unsafe_unretained _baz; + } + // ... + @end + +

    + +     + + + +

    + For projects that use Xcode 4.4 or later with clang, the use of + NSNumber literals + is allowed. Note however that this will limit the portability of your + code to other toolchains. +

    +     + +

    + NSNumber literals are used just like Objective C string literals. + Boxing is used when necessary. Code using NSNumber literals can be + deployed on any iOS/MacOS system. + + NSNumber *fortyTwo = @42; + NSNumber *piOverTwo = @(M_PI / 2); + enum { + kMyEnum = 2; + }; + NSNumber *myEnum = @(kMyEnum); + +

    @@ -1692,7 +1745,7 @@ Revision 2.36 A class that implements the delegate pattern should:
    1. - Have an instance variable named delegate_ to reference + Have an instance variable named _delegate to reference the delegate.
    2. @@ -1700,7 +1753,7 @@ Revision 2.36 and setDelegate:.
    3. - The delegate_ object should not be retained. + The _delegate object should not be retained.

    @@ -1743,10 +1796,33 @@ Revision 2.36 + + + + + Trailing underscores were once preferred for instance variable names. + + +

    + Our style guide used to have a rule saying that instance variables + should be named with a trailing underscore, similar to the naming of + member variables in C++. This was changed to leading underscores to + be consistent with the broader Objective-C community, to better follow + Apple's official guidelines, and to allow for use of new compiler + features like automatic instance variable synthesis. New projects are + strongly encouraged to use leading underscores. Existing projects may + continue to use trailing underscores in new code to maintain + consistency with the rest of their codebase. +

    + +     + +     +

    -Revision 2.36 +Revision 2.48

    diff --git a/pyguide.html b/pyguide.html index 30357f3..3c6a3e0 100644 --- a/pyguide.html +++ b/pyguide.html @@ -95,11 +95,11 @@ var matched = id && EndsWith(id, suffix); if (matched) { var len = id.length - suffix.length; - ShowByName(matched.substring(0, len)); + ShowByName(id.substring(0, len)); if (anchor.scrollIntoView) { anchor.scrollIntoView(); } - + return; } node = node.parentNode; @@ -136,7 +136,7 @@

    Google Python Style Guide

    - Revision 2.39 + Revision 2.45

    @@ -424,8 +424,9 @@ from sound.effects import echo unless you are re-raising the exception or in the outermost block in your thread (and printing an error message). Python is very tolerant in this regard and except: will - really catch everything including Python syntax errors. It is - easy to hide real bugs using except:. + really catch everything including misspelled names, sys.exit() + calls, Ctrl+C interrupts, unittest failures and all kinds of + other exceptions that you simply don't want to catch.
  • Minimize the amount of code in a try/except block. The larger the body of the try, the more likely that an @@ -988,8 +989,10 @@ from sound.effects import echo Use string methods instead of the string module where possible. Use function call syntax instead of apply. Use list comprehensions - and for loops instead of filter, - map, and reduce. + and for loops instead of filter and + map when the function argument would have been an + inlined lambda anyway. Use for loops instead of + reduce. 
    No:  words = string.split(foo, ':')
 
@@ -1279,7 +1284,7 @@ from sound.effects import echo
     
    
       Make note of the indentation of the elements in the line
       continuation examples above; see the
-      indentation
+      indentation
       section for explanation.
    @@ -1458,7 +1463,7 @@ from sound.effects import echo ▶
    Most .py files do not need to start with a - #! line. Start the main file of a binary with + #! line. Start the main file of a program with #!/usr/bin/python.
    • -

    Marks a variable as read-only and suitable for inlining. - Generates warnings if it is rewritten.

    -

    Constants should also be ALL_CAPS, but the annotation - should help eliminate reliance on the naming convention. - Although @final is listed at jsdoc.org and is supported as - equivalent to @const in the compiler, it is discouraged. - @const is consistent with JS1.5's const keyword. Note that - changes to properties of const objects are not currently - prohibited by the compiler (inconsistent with C++ const - semantics). The type declaration can be omitted if it can be - clearly inferred. If present, it must be on its own line. An - additional comment about the variable is optional.

    +

    Marks a variable (or property) as read-only and suitable + for inlining.

    + +

    A @const variable is a immutable pointer to + a value. If a variable or property marked as + @const is overwritten, JSCompiler will give + warnings.

    + +

    The type declaration of a constant value can be omitted + if it can be clearly inferred. An additional comment about + the variable is optional.

    + +

    When @const is applied to a method, it + implies the method is not only not overwritable, but also + that the method is finalized — + not overridable in subclasses.

    + +

    For more on @const, see the + Constants section.

    +
    @dict + @dict Description +

    For example:

    + + /** + * @constructor + * @dict + */ + function Foo(x) { + this['x'] = x; + } + var obj = new Foo(123); + var num = obj.x; // warning + + (/** @dict */ { x: 1 }).x = 123; // warning + +     		+ When a constructor (Foo in the example) is + annotated with @dict, you can only use the + bracket notation to access the properties of Foo + objects. + The annotation can also be used directly on object literals. +
    @enum @@ -2353,6 +2631,32 @@
    @expose + @expose +

    For example:

    + + /** @expose */ + MyClass.prototype.exposedProperty = 3; + +     		+

    + Declares an exposed property. Exposed properties + will not be removed, or renamed, or collapsed, + or optimized in any way by the compiler. No properties + with the same name will be able to be optimized either. +

    + +

    + @expose should never be used in library code, + because it will prevent that property from ever getting + removed. +

    +
    @extends @@ -2373,8 +2677,9 @@ - Used with @constructor to indicate that a class inherits from - another class. Curly braces around the type are optional. + Used with @constructor to indicate that a class + inherits from another class. Curly braces around the type are + optional.
    - Used with @constructor to indicate that a class implements an - interface. Curly braces around the type are optional. + Used with @constructor to indicate that a class + implements an interface. Curly braces around the type are + optional.
    -

    Deprecated. Use @override - instead.

    +

    Deprecated. Use + @override instead.

    Indicates that a method or property of a subclass intentionally hides a method or property of the superclass, and has exactly the same documentation. Notice that - @inheritDoc implies @override. + @inheritDoc implies @override
    - Anything marked by @license or @preserve will be retained by - the compiler and output at the top of the compiled code for - that file. This annotation allows important notices (such as - legal licenses or copyright text) to survive compilation - unchanged. Line breaks are preserved. + Anything marked by @license or + @preserve will be retained by the compiler and + output at the top of the compiled code for that file. This + annotation allows important notices (such as legal licenses or + copyright text) to survive compilation unchanged. Line breaks + are preserved.
    Reference a lookup to another class function or method.
    @struct + @struct Description +

    For example:

    + + /** + * @constructor + * @struct + */ + function Foo(x) { + this.x = x; + } + var obj = new Foo(123); + var num = obj['x']; // warning + obj.y = "asdf"; // warning + + Foo.prototype = /** @struct */ { + method1: function() {} + }; + Foo.prototype.method2 = function() {}; // warning + +     		+ When a constructor (Foo in the example) is + annotated with @struct, you can only use the dot + notation to access the properties of Foo objects. + Also, you cannot add new properties to Foo + objects after they have been created. + The annotation can also be used directly on object literals. +
    @supported @@ -2772,7 +3114,7 @@

    For example:

    /** - * @suppress {deprecation} + * @suppress {deprecated} */ function f() { deprecatedVersionOfF(); @@ -2782,6 +3124,7 @@     		Suppresses warnings from tools. Warning categories are separated by |. +
    - Identifies the type of a variable, property, or expression. + Identifies the type + of a variable, property, or expression. Curly braces are not required around most types, but some projects mandate them for all types, for consistency.