From 5684bbc8b5eda7592399f144eda966846117aed9 Mon Sep 17 00:00:00 2001 From: "mark@chromium.org" Date: Fri, 12 Jul 2013 18:53:13 +0000 Subject: [PATCH] Update C++ style guide to 3.260: - Add boost::bimap to the list of allowed Boost libraries. - C++11: remove mention of constexpr. - Remove noun/verb naming rules, and consolidate "General Naming Rules". - C++11: allow variadic templates. - Revise guidance on function definition comments. - Clarify that one space is sufficient before trailing /* */ comments. - C++11: allow alias templates. - C++11: allow , deprecate Boost array. - C++11: allow unique_ptr, deprecate Boost pointer container. - C++11: allow braced initializer lists. Update Objective-C style guide to 2.56: - Add details on constant declarations to clarify naming and scope issues. - Update link to Apple's Objective-C guide. - Allow left-aligning multi-block method invocation segments. - Add section on container literals. Update Python style guide to 2.54: - Allow str.format in addition to the % operator. - Allow #!/usr/bin/python2 and #!/usr/bin/python3. - Move the closing brace example from column 4 to 0. - Remove the requirement to use named parameters for arguments with defaults. Update HTML/CSS style guide to 2.23: - No changes. Update JavaScript style guide to 2.82: - Fix typos, whitespace, and character entities. - Include property descriptions in the clause about omitting obvious comments. - Make file overviews optional. - Fix example in "HTML in JSDoc" section. - Remove the semicolon-insertion language from the operators section. - State that complete sentences are recommended but not required. - Document usage of goog.scope to declare new classes. Update Common Lisp style guide to 1.20: - Indicate both variable and function predicates require a "p". - Make the abbreviations rules consistent and in one location. - Don't allow for the use of &AUX. - Allow for "body" and "end" as exceptions to the suffix rule. - Use the TODO convention to mark code that needs to be addressed. - Remove file maintainership requirements, require a description. - Change top-level form requirements to the length of a page. - Remove "don't be clever". --- cppguide.xml | 434 +++++++++++++++++++++++++++++--------------- htmlcssguide.xml | 6 +- javascriptguide.xml | 98 ++++++---- lispguide.xml | 170 +++++------------ objcguide.xml | 125 ++++++++++++- pyguide.html | 49 +++-- 6 files changed, 537 insertions(+), 345 deletions(-) diff --git a/cppguide.xml b/cppguide.xml index e87b36f..a0c2abf 100644 --- a/cppguide.xml +++ b/cppguide.xml @@ -4,7 +4,7 @@

-Revision 3.245 +Revision 3.260

@@ -737,6 +737,14 @@ Tashana Landray int j = g(); // Good -- declaration has initialization. + + vector<int> v; + v.push_back(1); // Prefer initializing using brace initialization. + v.push_back(2); + + + vector<int> v = {1, 2}; // Good -- v starts initialized. +

Note that gcc implements for (int i = 0; i < 10; ++i) correctly (the scope of i is @@ -779,8 +787,6 @@ Tashana Landray Static or global variables of class type are forbidden: they cause hard-to-find bugs due to indeterminate order of construction and destruction. - However, such variables are allowed if they are constexpr: - they have no dynamic initialization or destruction.

@@ -967,6 +973,12 @@ Tashana Landray exceptions. Such exceptions should be clearly marked with comments.

+

+ Finally, constructors that take only an initializer_list may be + non-explicit. This is to permit construction of your type using the + assigment form for brace init lists (i.e. MyType m = {1, 2} + ). +

@@ -1453,8 +1465,9 @@ Tashana Landray - If you actually need pointer semantics, scoped_ptr - is great. You should only use std::tr1::shared_ptr + If you actually need pointer semantics, unique_ptr + is great, and scoped_ptr is fine if you need to support + older versions of C++. You should only use shared_ptr with a non-const referent when it is truly necessary to share ownership of an object (e.g. inside an STL container). You should never use auto_ptr. @@ -1481,11 +1494,15 @@ Tashana Landray
+
unique_ptr
+
See below.
scoped_ptr
-
Straightforward and risk-free. Use wherever appropriate.
+
Prefer unique_ptr unless C++03 compatibility is + required.
auto_ptr
-
Confusing and bug-prone ownership-transfer semantics. Do not use. -
+
Confusing and bug-prone ownership-transfer semantics. Use + unique_ptr instead, if possible.
+
shared_ptr
Safe with const referents (i.e. shared_ptr<const @@ -2162,8 +2179,6 @@ Tashana Landray Use const whenever it makes sense. - With C++11, - constexpr is a better choice for some uses of const. @@ -2248,51 +2263,6 @@ Tashana Landray - - - In C++11, use constexpr - to define true constants or to ensure constant initialization. - - - - Some variables can be declared constexpr - to indicate the variables are true constants, - i.e. fixed at compilation/link time. - Some functions and constructors can be declared constexpr - which enables them to be used - in defining a constexpr variable. - - - Use of constexpr enables - definition of constants with floating-point expressions - rather than just literals; - definition of constants of user-defined types; and - definition of constants with function calls. - - - Prematurely marking something as constexpr - may cause migration problems if later on it has to be downgraded. - - Current restrictions on what is allowed - in constexpr functions and constructors - may invite obscure workarounds in these definitions. - - -

- constexpr definitions enable a more robust - specification of the constant parts of an interface. - Use constexpr to specify true constants - and the functions that support their definitions. - Avoid complexifying function definitions to enable - their use with constexpr. - Do not use constexpr to force inlining. -

- - - - - - Of the built-in C++ integer types, the only one used @@ -2735,9 +2705,7 @@ Tashana Landray

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 + brace-initialization can be confusing. The declarations auto x(3); // Note: parentheses. auto y{3}; // Note: curly braces. @@ -2757,7 +2725,8 @@ Tashana Landray

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

+ variables, or for class members. Never assign a braced initializer list + to an auto-typed variable.

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 @@ -2766,6 +2735,88 @@ Tashana Landray + +

+ You may use brace initialization. + + +

In C++03, aggregate types (arrays and structs with no constructor) could + be initialized using braces. + + struct Point { int x; int y; }; + Point p = {1, 2}; +

+ +

In C++11, this syntax has been expanded for use with all other datatypes. + The brace initialization form is called braced-init-list. Here are + a few examples of its use. + + // Vector takes lists of elements. + vector<string> v{"foo", "bar"}; + + // The same, except this form cannot be used if the initializer_list + // constructor is explicit. You may choose to use either form. + vector<string> v = {"foo", "bar"}; + + // Maps take lists of pairs. Nested braced-init-lists work. + map<int, string> m = {{1, "one"}, {2, "2"}}; + + // braced-init-lists can be implicitly converted to return types. + vector<int> test_function() { + return {1, 2, 3}; + } + + // Iterate over a braced-init-list. + for (int i : {-1, -2, -3}) {} + + // Call a function using a braced-init-list. + void test_function2(vector<int> v) {} + test_function2({1, 2, 3}); +

+ +

User data types can also define constructors that take + initializer_list, which is automatically created from + braced-init-list: + + class MyType { + public: + // initializer_list is a reference to the underlying init list, + // so it can be passed by value. + MyType(initializer_list<int> init_list) { + for (int element : init_list) {} + } + }; + MyType m{2, 3, 5, 7}; +

+ +

Finally, brace initialization can also call ordinary constructors of + data types that do not have initializer_list constructors. + + double d{1.23}; + // Calls ordinary constructor as long as MyOtherType has no + // initializer_list constructor. + class MyOtherType { + public: + explicit MyOtherType(string); + MyOtherType(int, string); + }; + MyOtherType m = {1, "b"}; + // If the constructor is explicit, you can't use the "= {}" form. + MyOtherType m{"b"}; +

+ +

Never assign a braced-init-list to an auto local variable. In the + single element case, what this means can be confusing. + + auto d = {1.23}; // d is an initializer_list<double> + + + auto d = double{1.23}; // Good -- d is a double, not an initializer_list. + +

+ + + Use only approved libraries from the Boost library collection. @@ -2801,15 +2852,6 @@ Tashana Landray
  • Compressed Pair from boost/compressed_pair.hpp
    • -
  • - Pointer Container from boost/ptr_container except - serialization and wrappers for containers not in the C++03 - standard (ptr_circular_buffer.hpp and - ptr_unordered*) -
    • -
  • - Array from boost/array.hpp -
  • The Boost Graph Library (BGL) from boost/graph, except serialization (adj_list_serialize.hpp) and @@ -2835,10 +2877,29 @@ Tashana Landray boost/polygon/voronoi_builder.hpp, boost/polygon/voronoi_diagram.hpp, and boost/polygon/voronoi_geometry_type.hpp
    • +
  • + Bimap from boost/bimap +
    • We are actively considering adding other Boost features to the list, so - this rule may be relaxed in the future. + this list may be expanded in the future. +

    + The following libraries are permitted, but their use is discouraged + because they've been superseded by standard libraries in C++11: +

    +

    @@ -2910,14 +2971,21 @@ Tashana Landray
  • 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.
    • + headers.
  • Use of local types as template parameters.
  • nullptr and nullptr_t.
  • static_assert.
    • +
  • Everything in <array>.
  • Everything in <tuple>.
    • +
  • Variadic templates.
    • +
  • Alias templates (the new using syntax) may be used. + Don't use an alias declaration where a typedef will work.
    • +
  • unique_ptr, with restrictions (see + below).
    • +
  • Brace initialization syntax. See + the full section for more + detail.
    • Other features will be approved individually as appropriate. Avoid writing code that is incompatible with C++11 (even though it @@ -2927,6 +2995,59 @@ Tashana Landray + + + Use unique_ptr freely within classes and functions, + but do not use it to transfer ownership outside of a single .cc/.h + pair. + + + + unique_ptr is a "smart" pointer type which expresses + exclusive ownership of the underlying object. It provides "move + semantics", which enables it to be stored in containers and used + as a function parameter or return value, even though it cannot be + copied (to preserve the unique-ownership property). + + +
      +
    • It fully automates memory management of singly-owned pointers, + virtually eliminating the risk of leaking the underlying memory.
      • +
    • It provides a single, universal abstraction for singly-owned + pointers, replacing close to a dozen overlapping partial solutions + in common use at Google.
      • +
    • It can be passed into and returned from functions, providing + a self-documenting and compiler-enforced way to transfer ownership + between scopes.
      • +
    • Its performance is essentially identical to a plain pointer.
      • +
    +     + +
      +
    • It cannot be used in code that requires C++03 compatibility.
      • +
    • Move semantics implicitly rely on rvalue references, + a new C++11 feature which is unfamiliar to many Googlers.
      • +
    • Google code currently uses a completely different set of + conventions for ownership transfer. Mixing unique_ptr + with the existing conventions could add complexity and create + confusion.
      • +
    • Best practices for using unique_ptr within Google + have not yet been established.
      • +
    +     + +

    Use of unique_ptr as a class member or local variable + is encouraged, as is storing unique_ptr in containers + that support it. However, for the time being it is forbidden to use + unique_ptr as a function parameter or return value, + except for functions that are local to a single .cc/.h pair.

    +

    Note that the std::move() function, which is often + used to pass unique_ptr into function calls, remains + forbidden.

    +     + +     + @@ -2950,72 +3071,30 @@ Tashana Landray Function names, variable names, and filenames should be - descriptive; eschew abbreviation. Types and variables should be - nouns, while functions should be "command" verbs. + descriptive; eschew abbreviation. - -

    - Give as descriptive a name as possible, within reason. Do - not worry about saving horizontal space as it is far more - important to make your code immediately understandable by a - new reader. Examples of well-chosen names: -

    - - int num_errors; // Good. - int num_completed_connections; // Good. - -

    - Poorly-chosen names use ambiguous abbreviations or arbitrary - characters that do not convey meaning: -

    - - int n; // Bad - meaningless. - int nerr; // Bad - ambiguous abbreviation. - int n_comp_conns; // Bad - ambiguous abbreviation. - -

    - Type and variable names should typically be nouns: e.g., - FileOpener, - - num_errors. -

    -

    - Function names should typically be imperative (that is they - should be commands): e.g., OpenFile(), - set_num_errors(). There is an exception for - accessors, which, described more completely in Function Names, should be named - the same as the variable they access. -

    -     - - -

    - Do not use abbreviations unless they are extremely well - known outside your project. For example: -

    - - // Good - // These show proper names with no abbreviations. - int num_dns_connections; // Most people know what "DNS" stands for. - int price_count_reader; // OK, price count. Makes sense. - - - // Bad! - // Abbreviations can be confusing or ambiguous outside a small group. - int wgc_connections; // Only your group knows what this stands for. - int pc_reader; // Lots of things can be abbreviated "pc". - -

    - Never abbreviate by leaving out letters: -

    - - int error_count; // Good. - - - int error_cnt; // Bad. - -     +

    + Give as descriptive a name as possible, within reason. Do + not worry about saving horizontal space as it is far more + important to make your code immediately understandable by a + new reader. Do not use abbreviations that are ambiguous or + unfamiliar to readers outside your project, and do not + abbreviate by deleting letters within a word. +

    + + int price_count_reader; // No abbreviation. + int num_errors; // "num" is a widespread convention. + int num_dns_connections; // Most people know what "DNS" stands for. + + + int n; // Meaningless. + int nerr; // Ambiguous abbreviation. + int n_comp_conns; // Ambiguous abbreviation. + int wgc_connections; // Only your group knows what this stands for. + int pc_reader; // Lots of things can be abbreviated "pc". + int cstmr_id; // Deletes internal letters. +     @@ -3532,9 +3611,9 @@ Tashana Landray

    - Each function definition should have a comment describing - what the function does if there's anything tricky about how it does - its job. For example, in the definition comment you might + If there is anything tricky about how a function does its + job, the function definition should have an explanatory + comment. 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 the function in the way you did rather than using a viable @@ -3640,6 +3719,7 @@ Tashana Landray // thus the comment lines up with the following comments and code. DoSomethingElse(); // Two spaces before line comments normally. } + DoSomething(); /* For trailing block comments, one space is fine. */ @@ -4067,6 +4147,49 @@ Tashana Landray + +

    + On one line if it fits, otherwise wrap at the open brace. + + +

    + Put everything on one line where possible. If everything can't fit + on one line, the open brace should be the last character on its line, + and the close brace should be the first character on its line. +

    + + // Examples of braced init list on a single line. + return {foo, bar}; + functioncall({foo, bar}); + pair<int, int> p{foo, bar}; + + // When you have to wrap. + MyType m = { + superlongvariablename1, + superlongvariablename2, + {short, interior, list}, + { + interiorwrappinglist, + interiorwrappinglist2 + } + }; + + // Wrapping inside a function call. + function({ + wrapped, long, + list, here + }); + + // If the variable names are really long. + function( + { + wrapped, + list + }); + + + + Prefer no spaces inside parentheses. The else @@ -4354,18 +4477,39 @@ Tashana Landray - Your choice of = or (). + Your choice of =, (), or {}.

    - You may choose between = and (); the - following are all correct: + You may choose between =, (), and + {}; the following are all correct:

    int x = 3; int x(3); - string name("Some Name"); + int x{3}; string name = "Some Name"; + string name("Some Name"); + string name{"Some Name"}; + +

    + Be careful when using the {} on a type that takes an + initializer_list in one of its constructors. The + {} syntax prefers the initializer_list + constructor whenever possible. To get the non- + initializer_list constructor, use (). +

    + + vector<int> v(100, 1); // A vector of 100 1s. + vector<int> v{100, 1}; // A vector of 100, 1. + +

    + Also, the brace form prevents narrowing of integral types. This can + prevent some types of programming errors. +

    + + int pi(3.14); // OK -- pi == 3. + int pi{3.14}; // Compile error: narrowing conversion.     @@ -4547,7 +4691,7 @@ Tashana Landray void f(bool b) { // Open braces should always have a space before them. ... int i = 0; // Semicolons usually have no space before them. - int x[] = { 0 }; // Spaces inside braces for array initialization are + int x[] = { 0 }; // Spaces inside braces for braced-init-list are int x[] = {0}; // optional. If you use them, put them on both sides! // Spaces around the colon in inheritance and initializer lists. class Foo : public Bar { @@ -4803,7 +4947,7 @@ Tashana Landray

    -Revision 3.245 +Revision 3.260

    diff --git a/htmlcssguide.xml b/htmlcssguide.xml index 2d6edeb..d8caf13 100644 --- a/htmlcssguide.xml +++ b/htmlcssguide.xml @@ -3,7 +3,7 @@

    - Revision 2.21 + Revision 2.23

    @@ -1086,6 +1086,8 @@ + +

    Be consistent. @@ -1109,7 +1111,7 @@

    - Revision 2.21 + Revision 2.23

    diff --git a/javascriptguide.xml b/javascriptguide.xml index 282f8b7..a33c481 100644 --- a/javascriptguide.xml +++ b/javascriptguide.xml @@ -3,7 +3,7 @@

    - Revision 2.72 + Revision 2.82

    @@ -96,8 +96,8 @@ boolean) are constant values.

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

    @@ -112,7 +112,8 @@ lack of support in Internet Explorer).

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

    + implies that the method should not be overridden in subclasses. +

    @@ -209,12 +210,12 @@ -

    JavaScript requires statements to end with a semicolon, - except when it thinks it can safely infer their existence. In each - of these examples, a function declaration or object or array literal - is used inside a statement. The closing brackets are not enough to - signal the end of the statement. Javascript never ends a statement - if the next token is an infix or bracket operator.

    +

    JavaScript requires statements to end with a semicolon, except when + it thinks it can safely infer their existence. In each of these + examples, a function declaration or object or array literal is used + inside a statement. The closing brackets are not enough to signal + the end of the statement. Javascript never ends a statement if the + next token is an infix or bracket operator.

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

     @@ -1147,7 +1148,7 @@ 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:

    + this (see below for how to alias a constructor):

    goog.scope(function() { @@ -1161,7 +1162,7 @@ are aliasing.

    - goog.provide('my.module'); + goog.provide('my.module.SomeType'); goog.require('goog.dom'); goog.require('goog.ui.Button'); @@ -1169,9 +1170,16 @@ goog.scope(function() { var Button = goog.ui.Button; var dom = goog.dom; - var module = my.module; - module.button = new Button(dom.$('my-button')); + // Alias new types after the constructor declaration. + my.module.SomeType = function() { ... }; + var SomeType = my.module.SomeType; + + // Declare methods on the prototype as usual: + SomeType.prototype.findButton = function() { + // Button as aliased above. + this.button = new Button(dom.getElement('my-button')); + }; ... }); // goog.scope @@ -1224,10 +1232,12 @@ -

    Always put the operator on the preceding line, so that you don't - have to think about implicit semi-colon insertion issues. Otherwise, +

    Always put the operator on the preceding line. Otherwise, line breaks and indentation follow the same rules as in other - Google style guides.

    + Google style guides. This operator placement was initially agreed + upon out of concerns about automatic semicolon insertion. In fact, + semicolon insertion cannot happen before a binary operator, but new + code should stick to this style for consistency.

    var x = a ? b : c; // All on one line if it will fit. @@ -1325,7 +1335,7 @@

    Note that these semantics differ from those of C++ and Java, in that they grant private and protected access to all code in the same file, not just in the same class or class hierarchy. Also, unlike in C++, - private properties cannot be overriden by a subclass. + private properties cannot be overridden by a subclass.

    // File 1. @@ -1892,12 +1902,12 @@ - An Object in which the keys are numbers and the values - are strings.

    Note that in JavaScript, the keys are always + An Object in which the keys are numbers and the values are + strings.

    Note that in JavaScript, the keys are always 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 + So the key will always be a string in for...in loops. But the + compiler will verify the type of the key when indexing into the object. @@ -2205,15 +2215,16 @@

    All files, classes, methods and properties should be documented with JSDoc comments with the appropriate tags - and types. Textual descriptions for methods, - method parameters and method return values should be included - unless obvious from the method or parameter name. + and types. Textual descriptions for properties, + methods, method parameters and method return values should be included + unless obvious from the property, method, or parameter name.

    Inline comments should be of the // variety.

    -

    Avoid sentence fragments. Start sentences with a properly - capitalized word, and end them with punctuation.

    +

    Complete sentences are recommended but not required. + Complete sentences should use appropriate capitalization + and punctuation.

    The JSDoc syntax is based on @@ -2288,7 +2299,7 @@

    It'll come out like this:

    - Computes weight based on three factors: items sent items received items received + Computes weight based on three factors: items sent items received last timestamp

    Instead, do this:

    @@ -2313,10 +2324,13 @@

    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 and any - dependencies or compatibility information. As an example:

    + File overviews are generally recommended whenever a file consists of + more than a single class definition. The top level comment is + designed to orient readers unfamiliar with the code to what is in + this file. If present, it should provide a description of the + file's contents and any dependencies or compatibility information. + As an example: +

    /** @@ -2359,7 +2373,7 @@ * Operates on an instance of MyClass and returns something. * @param {project.MyClass} obj Instance of MyClass which leads to a long * comment that needs to be wrapped to two lines. - * @return {boolean} Whether something occured. + * @return {boolean} Whether something occurred. */ function PR_someMethod(obj) { // ... @@ -2461,7 +2475,7 @@ * @const */ mynamespace.Request.prototype.initialize = function() { - // This method cannot be overriden in a subclass. + // This method cannot be overridden in a subclass. } @@ -2806,7 +2820,9 @@ Polygon.prototype.getSides = function() {};     - Used to indicate that the function defines an inteface. + + Used to indicate that the function defines an interface. + @@ -3204,10 +3220,10 @@ - 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. + 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. @@ -3237,6 +3253,8 @@ + +

    You may also see other types of JSDoc annotations in third-party code. These annotations appear in the @@ -3539,7 +3557,7 @@

    - Revision 2.72 + Revision 2.82

    diff --git a/lispguide.xml b/lispguide.xml index e09dd91..acc6219 100644 --- a/lispguide.xml +++ b/lispguide.xml @@ -5,7 +5,7 @@

    -Revision 1.18 +Revision 1.20

    @@ -313,10 +313,6 @@ Robert Brown Ideally, there should be no way to look at lines of code and recognize it as "Fred's code" by its style. -
  • - Don't be "clever" — - do the simplest thing that could possibly work properly. -
  • Be precise.
    • @@ -454,16 +450,6 @@ Robert Brown -

    - Note that if you have a "clever" implementation trick, - and your trick really is clever, - then you must definitely not include it in business specific code; - but it may have its place in an open-source library used by the code. - If your idea is not general purpose enough to have any users - beyond your regular business users, - then it is definitely either not clever enough or way too clever, - and in either case does not belong in the code. -

    @@ -575,10 +561,10 @@ Robert Brown you should choose the shorter spelling.

    - You must avoid using abbreviations for words, - unless it's a word that is used very frequently, - in which case you must use - the same abbreviation consistently. + You must use only common and domain-specific abbreviations, and + must be consistent with these abbreviations. You may abbreviate + lexical variables of limited scope in order to avoid overly-long + symbol names.

    @@ -712,37 +698,19 @@ Robert Brown

    - You must include maintainership and other important information - at the top of each source file. + You should include a description at the top of each source file.

    - You should not include a copyright statement in source files. + You should include neither authorship nor copyright information in a source file.

    - Every source file may begin with a one-line description of the file. + Every source file should begin with a brief description + of the contents of that file.

    - After that optional description, - every source file may prominently include a statement - about who originally wrote the code, - made major changes, and/or is the current owner/maintainer. - This makes it easier for hackers to locate - whom to ask questions about the code, - or to identify that no one is left to reply to such inquiries. - However, consider that the information - is not very helpful if it is not maintained; - unless it brings information - that cannot be easily extracted from source control, - it is better skipped. -

    -

    - After that optional statement, every file should follow with - a brief explanation of what the file contains. -

    -

    - After that explanation, every file should start the code itself with an + After that description, every file should start the code itself with an (in-package :package-name) form.

    @@ -759,6 +727,11 @@ Robert Brown (in-package #:varint) (declaim #.*optimize-default*) +

    + You should not include authorship information at the top of a file, + that information is available from version control and + OWNERS. +

    You should not include copyright information in individual source code files. An exception is made for files meant to be disseminated as standalone. @@ -805,9 +778,10 @@ Robert Brown what each of the separated parts of the function does.

    - Every top-level form - should be fewer than 61 lines long, - including comments but excluding the documentation string. + You should strive to keep top-level forms, + including comments but excluding the documentation string, of + appropriate length; preferrably short. Forms extending beyond a + single page should be rare and their use should be justfied. This applies to each of the forms in an eval-when, rather than to the eval-when itself. Additionally, defpackage forms may be longer, @@ -1114,66 +1088,16 @@ Robert Brown

    - You must follow the convention of using --- - for comments requiring special attention, - including unobvious tricks, TODO items, questions, breakage, danger. + You must follow the convention of using TODO comments + for code requiring special attention. + For code using unobvious forms, you must include a comment. -
      -
    • - ;--- prefixes a cautionary comment, - e.g. explaining why the code in question is particularly - tricky, delicate, or non-obvious. -
      • -
    • - ;---??? prefixes a serious question - which needs to be resolved soon, - by fixing either the code or its documentation. -
      • -
    • - ;---!!! identifies code which is broken, - but which for some reason you cannot fix at this time. - You should not use this often for new code. -
      • -
    • - ;---*** identifies active DANGER, - for instance where important functionality is stubbed out, - or a large design issue remains unresolved. - Anything so marked must be fixed - before code is rolled into production. -
      • -

    - You must sign and date - any of the above "requiring further attention" comments - (but not mere cautionary explanations). - You must use the - YYYY-MM-DD - format for dates to make automated processing of such dates easier. -

    -

    - This strategy ensures that grepping for ;--- - will always yield all the comments that require caution, - as well as whom to talk to about each one. -

    -

    - Only use ;--- on the first line of such a comment. - Other lines should use spaces to align vertically. - This way, grepping will also yield a count of the number of issues. -

    -

    - You should insert a space after this comment prefix. -

    -

    - You may use these with multiple-semicolon comments as well. -

    -

    - Some people like to use words like FIXME or TODO. - You may use these, but they must be preceded with ---. -

    -

    - Use TODO comments when the code is known to be incomplete - and you want to indicate what work remains to be done. + For comments requiring special attention, such as + incomplete code, todo items, questions, breakage, and danger, + include a TODO comment indicating the type of problem, + its nature, and any notes on how it may be addressed.

    The comments begin with TODO in all capital letters, @@ -1201,6 +1125,10 @@ Robert Brown ;;--- TODO(brown): Remove this code after release 1.7 or before November, 2012. +

    + For code that uses unobvious forms to accomplish a task, you must include a comment + stating the purpose of the form and the task it accomplishes. +

    @@ -1241,7 +1169,7 @@ Robert Brown You should use lower case. - You should not abbreviate. + You should follow the rules for Spelling and Abbreviations You should follow punctuation conventions. @@ -1274,17 +1202,8 @@ Robert Brown unless you have a well-documented overarching reason to, and permission from other hackers who review your proposal.

    -

    - Generally, you should do not abbreviate words. - You must avoid using abbreviations for words, - unless it's a word that is used very frequently, - in which case you must use - the same abbreviation consistently. - Abbreviations may also be used sparingly to avoid overly-long symbol names; - it's easy to run into 100-column limit when there are very long names! - You must especially avoid inconsistent abbreviations in exported names. - For lexical variables of limited scope, abbreviations are fine. -

    + See the section on Spelling and Abbreviations + for guidelines on using abbreviations.

    @@ -1402,12 +1321,12 @@ Robert Brown     - Names of predicate functions end with a "P". + Names of predicate functions and variables end with a "P".

    - You should name boolean-valued functions with a trailing - "P" or "-P", + You should name boolean-valued functions and variables with a + trailing "P" or "-P", to indicate they are predicates. Generally, you should use "P" when the rest of the function name is one word @@ -2248,7 +2167,7 @@ Robert Brown without a consensus among the developers of your system. Reader macros must not leak out of the system that uses them to clients of that system or other systems used in the same project. - You must software such as + You must use software such as cl-syntax or named-readtables to control how reader macros are used. This clients who desire it may use the same reader macros as you do. @@ -2261,6 +2180,8 @@ Robert Brown you should name the parameter with the suffix -form. This convention helps make it clearer to the macro's user which parameters are Lisp forms to be evaluated, and which are not. + The common names body and end are + exceptions to this rule.

    You should follow the so-called CALL-WITH style when it applies. @@ -2899,10 +2820,9 @@ Robert Brown

    You should make proper use of - &OPTIONAL, - &KEY, - and - &AUX arguments. + &OPTIONAL and + &KEY arguments. + You should not use &AUX arguments.

    @@ -2932,9 +2852,7 @@ Robert Brown and pass around a plist as a &REST argument.

    - You should avoid using &AUX arguments, - except in very short helper functions - where they allow you to eschew a LET. + You should avoid using &AUX arguments.

    You should avoid having both &OPTIONAL @@ -3890,7 +3808,7 @@ Robert Brown

    -Revision 1.18 +Revision 1.20

    diff --git a/objcguide.xml b/objcguide.xml index 6c7ae77..73fcecd 100644 --- a/objcguide.xml +++ b/objcguide.xml @@ -4,7 +4,7 @@

    -Revision 2.52 +Revision 2.56

    @@ -109,8 +109,8 @@ Revision 2.52 Note that this guide is not an Objective-C tutorial. We assume that the reader is familiar with the language. If you are new to Objective-C or need a refresher, please read - - The Objective-C Programming Language + + Programming with Objective-C .

    @@ -366,6 +366,10 @@ Revision 2.52 evenLongerKeyword:arg3 error:arg4]; +

    + Invocations containing inlined blocks may have + their segments left-aligned at a four space indent. +

    @@ -467,6 +471,11 @@ Revision 2.52 space between the ^( characters, but there is one space between the ) { characters. +
  • + Invocations containing inlined blocks may have their segments + left-aligned at a four-space indent. This helps when invocations + contain multiple inlined blocks. +
  • Two space indents inside blocks are also allowed, but should only be used when it's consistent with the rest of the project's code. @@ -521,10 +530,102 @@ Revision 2.52 // ... }; [_operationQueue addOperationWithBlock:largeBlock]; + + // An example with multiple inlined blocks in one invocation. + [myObject doSomethingWith:arg1 + firstBlock:^(Foo *a) { + // ... + } + secondBlock:^(Bar *b) { + // ... + }]; + + + For projects using Xcode 4.4 or later and clang, the use of container + (array and dictionary) literals is encouraged. If split across multiple + lines, the contents should be indented two spaces. + + +

    + If the collection fits on one line, put a single space after the opening + and before the closing brackets. +

    + + NSArray* array = @[ [foo description], @"Another String", [bar description] ]; + + NSDictionary* dict = @{ NSForegroundColorAttributeName : [NSColor redColor] }; + +

    + Not: +

    + + NSArray* array = @[[foo description], [bar description]]; + + NSDictionary* dict = @{NSForegroundColorAttributeName: [NSColor redColor]}; + + +

    + If the collection spans more than a single line, place the opening + bracket on the same line as the declaration, indent the body by two + spaces, and place the closing bracket on a new line that is indented to + the same level as the opening bracket. +

    + + NSArray* array = @[ + @"This", + @"is", + @"an", + @"array" + ]; + + NSDictionary* dictionary = @{ + NSFontAttributeName : [NSFont fontWithName:@"Helvetica-Bold" size:12], + NSForegroundColorAttributeName : fontColor + }; + + +

    + For dictionary literals, there should be one space before the colon and + at least one space after it (to optionally align the values). +

    + + NSDictionary* option1 = @{ + NSFontAttributeName : [NSFont fontWithName:@"Helvetica-Bold" size:12], + NSForegroundColorAttributeName : fontColor + }; + + NSDictionary* option2 = @{ + NSFontAttributeName : [NSFont fontWithName:@"Arial" size:12], + NSForegroundColorAttributeName : fontColor + }; + +

    + The following are all incorrect: +

    + + // There should be a space before the colon. + NSDictionary* wrong = @{ + AKey: @"b", + BLongerKey: @"c", + }; + + // The items should each be on a new line, or the entire expression + // should fit on one line. + NSDictionary* alsoWrong= @{ AKey : @"a", + BLongerKey : @"b" }; + + // There should be no variable space before the colon, only after. + NSDictionary* stillWrong = @{ + AKey : @"b", + BLongerKey : @"c", + }; + + +     @@ -794,8 +895,20 @@ Revision 2.52

    Constant names (#defines, enums, const local variables, etc.) should start with a lowercase k and then use mixed case to - delimit words, i.e. kInvalidHandle, - kWritePerm. + delimit words. For example: +

    + + const int kNumberOfFiles = 12; + NSString *const kUserKey = @"kUserKey"; + enum DisplayTinge { + kDisplayTingeGreen = 1, + kDisplayTingeBlue = 2 + }; + +

    + Because Objective-C does not provide namespacing, constants with global + scope should have an appropriate prefix to minimize the chance of name + collision, typically like kClassNameFoo.

    @@ -1838,7 +1951,7 @@ Revision 2.52

    -Revision 2.52 +Revision 2.56

    diff --git a/pyguide.html b/pyguide.html index 7213d7a..31fc512 100644 --- a/pyguide.html +++ b/pyguide.html @@ -136,7 +136,7 @@

    Google Python Style Guide

    - Revision 2.48 + Revision 2.54

    @@ -775,7 +775,7 @@ from sound.effects import echo

    Decision: - Okay to use with the following caveats: + Okay to use with the following caveat:

    Do not use mutable objects as default values in the function or method definition. @@ -785,17 +785,6 @@ from sound.effects import echo b = [] 

    No:  def foo(a, b=[]):
          ...
    -

    - Calling code must use named values for arguments with a default value. - This helps document the code somewhat and helps prevent and detect - interface breakage when more arguments are added. -

    -
    -def foo(a, b=1):
-    ...
    -
    Yes: foo(1)
-     foo(1, b=2)
    -
    No:  foo(1, 2)

    @@ -1250,6 +1239,7 @@ from sound.effects import echo
    • Long import statements.
    • URLs in comments.
      • +

    @@ -1454,7 +1444,7 @@ from sound.effects import echo dictionary = { 'foo': 1, 'long_name': 2, - } + } 
    No:
   foo       = 1000  # comment
   long_name = 2     # comment that should not be aligned
@@ -1462,7 +1452,7 @@ from sound.effects import echo
   dictionary = {
       'foo'      : 1,
       'long_name': 2,
-      }
    + } @@ -1476,8 +1466,11 @@ from sound.effects import echo ▶
    Most .py files do not need to start with a - #! line. Start the main file of a program with - #!/usr/bin/python. + #! line. Start the main file of a + program with + #!/usr/bin/python with an optional single digit + 2 or 3 suffix per + PEP-394.