diff --git a/cppguide.xml b/cppguide.xml index cdd0444..c61416f 100644 --- a/cppguide.xml +++ b/cppguide.xml @@ -4,7 +4,7 @@

-Revision 3.146 +Revision 3.154

@@ -1581,7 +1581,8 @@ Tashana Landray - We do not allow default function parameters. + We do not allow default function parameters, except in + a few uncommon situations explained below. @@ -1600,10 +1601,23 @@ Tashana Landray the new code. - 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. +

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

+

+ One 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. + string StrCat(const AlphaNum &a, + const AlphaNum &b = gEmptyAlphaNum, + const AlphaNum &c = gEmptyAlphaNum, + const AlphaNum &d = gEmptyAlphaNum); + @@ -2411,6 +2425,9 @@ Tashana Landray
  • Try not to use macros that expand to unbalanced C++ constructs, or at least document that behavior well.
    • +
  • Prefer not using ## to generate function/class/variable + names. +
    • @@ -2494,6 +2511,9 @@ Tashana Landray who might read and maintain code, we only allow an approved subset of Boost features. Currently, the following libraries are permitted:

    - - -

    Global variables

    + + +
    +

    Global variables

    ▶ - +
    Avoid global variables. - -
    +
    +
    +
    +

    Nested/Local/Inner Classes and Functions

    ▶ - +
    Nested/local/inner classes and functions are fine. - -
    +
    +
    +
    +

    List Comprehensions

    ▶ - +
    Okay to use for simple cases. - -
    +
    +
    + +
    +

    Default Iterators and Operators

    ▶ - +
    Use default iterators and operators for types that support them, like lists, dictionaries, and files. - -
    +

    - - -

    Generators

    +
    + +
    +

    Generators

    ▶ - +
    Use generators as needed. - -
    +
    +
    +
    +

    Lambda Functions

    ▶ - +
    Okay for one-liners. - -
    +
    +
    +
    +

    Default Argument Values

    ▶ - +
    Okay in most cases. - -
    +
    +
    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)
    
+    ...
    +
    Yes: foo(1)
+     foo(1, b=2)
    +
    No:  foo(1, 2)

    -     - -

    Properties

    +
    + +
    +

    Properties

    ▶ - +
    Use properties for accessing or setting data where you would normally have used simple, lightweight accessor or setter methods. - -
    +

    - - -

    True/False evaluations

    +
    + +
    +

    True/False evaluations

    ▶ - +
    Use the "implicit" false if at all possible. - -
    +
  • @@ -876,18 +907,20 @@ from sound.effects import echo evaluates to true.

    • - - -

    Deprecated Language Features

    +
    + +
    +

    Deprecated Language Features

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

    - - -

    Lexical Scoping

    +
    + +
    +

    Lexical Scoping

    ▶ - +
    Okay to use. - -
    +

    Pros: @@ -956,7 +991,7 @@ from sound.effects import echo Cons: Can lead to confusing bugs. Such as this example based on PEP-0227: -

    +
     i = 4
 def foo(x):
     def bar():
@@ -966,7 +1001,7 @@ from sound.effects import echo
     # ...
     for i in x:  # Ah, i *is* local to Foo, so this is what Bar sees
         print i,
-    bar()
    
+    bar()

    So foo([1, 2, 3]) will print 1 2 3 3, not 1 2 3 4. @@ -976,14 +1011,16 @@ from sound.effects import echo Decision: Okay to use.

    -     - -

    Function and Method Decorators

    +
    + +
    +

    Function and Method Decorators

    ▶ - +
    Use decorators judiciously when there is a clear advantage. - -
    +
    is equivalent to: - 
    +      
     class C(object):
     def method(self):
         # method body ...
     method = my_decorator(method)
 
-
    
+

    Pros: Elegantly specifies some transformation on a method; the @@ -1045,14 +1082,16 @@ from sound.effects import echo main for more discussion.

    -     - -

    Threading

    +
    + +
    +

    Threading

    ▶ - +
    Do not rely on the atomicity of built-in types. - -
    +
    +
    +
    +

    Power Features

    ▶ - +
    Avoid these features. - -
    +
    +
    + +
    +

    Python Style Rules

    +
    +

    Semicolons

    ▶ - +
    Do not terminate your lines with semi-colons and do not use semi-colons to put two commands on the same line. - -
    +
    +
    +
    +

    Line length

    ▶ - +
    Maximum line length is 80 characters. - -
    +

    @@ -1159,9 +1205,9 @@ from sound.effects import echo implicit line joining.

    - 
    +    
     x = ('This will build a very long long '
-     'long long long long long long string')
    
+     'long long long long long long string')

    Make note of the indentation of the elements in the line @@ -1169,14 +1215,16 @@ from sound.effects import echo indentation section for explanation.

    -     - -

    Parentheses

    +
    + +
    +

    Parentheses

    ▶ - +
    Use parentheses sparingly. - -
    +
    +
    + +
    +

    Indentation

    ▶ - +
    Indent your code blocks with 4 spaces. - -
    +
    +
    + +
    +

    Blank Lines

    ▶ - +
    Two blank lines between top-level definitions, one blank line between method definitions. - -
    +
    +
    +
    +

    Whitespace

    ▶ - +
    Follow standard typographic rules for the use of spaces around punctuation. - -
    +

    No whitespace before the open paren/bracket that starts an argument list, indexing or slicing.

    - 
    Yes: spam(1)
     -
    No:  spam (1)
     -
    Yes: dict['key'] = list[index]
     -
    No:  dict ['key'] = list [index]
     + 
    Yes: spam(1)
    +
    No:  spam (1)
    +
    Yes: dict['key'] = list[index]
    +
    No:  dict ['key'] = list [index]

    Surround binary operators with a single space on either side for @@ -1298,48 +1352,50 @@ from sound.effects import echo insertion of spaces around arithmetic operators but always be consistent about whitespace on either side of a binary operator.

    -
    Yes: x == 1
     -
    No:  x<1
     +
    Yes: x == 1
    +
    No:  x<1

    Don't use spaces around the '=' sign when used to indicate a keyword argument or a default parameter value.

    -
    Yes: def complex(real, imag=0.0): return magic(r=real, i=imag)
     -
    No:  def complex(real, imag = 0.0): return magic(r = real, i = imag)
     +
    Yes: def complex(real, imag=0.0): return magic(r=real, i=imag)
    +
    No:  def complex(real, imag = 0.0): return magic(r = real, i = imag)

    Don't use spaces to vertically align tokens on consecutive lines, since it becomes a maintenance burden (applies to :, #, =, etc.):

    -
    Yes:
+
    Yes:
   foo = 1000  # comment
   long_name = 2  # comment that should not be aligned
 
   dictionary = {
       "foo": 1,
       "long_name": 2,
-      }
    
-
    No:
+      }
    
+
    No:
   foo       = 1000  # comment
   long_name = 2     # comment that should not be aligned
 
   dictionary = {
       "foo"      : 1,
       "long_name": 2,
-      }
    
+      }
    -     - -

    Python Interpreter

    +
    + +
    +

    Python Interpreter

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

    Comments

    ▶ - +
    Be sure to use the right style for module, function, method and in-line comments. - -
    +

    Classes @@ -1477,7 +1535,7 @@ from sound.effects import echo function's Args section.

    - 
    +    
     class SampleClass(object):
     """Summary of class here.
 
@@ -1497,7 +1555,7 @@ from sound.effects import echo
     def public_method(self):
         """Performs operation blah."""
 
-
    
+

    @@ -1512,7 +1570,7 @@ from sound.effects import echo commence. Non-obvious ones get comments at the end of the line.

    - 
    +    
     # We use a weighted dictionary search to find out where i is in
 # the array.  We extrapolate position based on the largest num
 # in the array and the array size and then do binary search to
@@ -1520,7 +1578,7 @@ from sound.effects import echo
 
 if i & (i-1) == 0:        # true iff i is a power of 2
 
-
    
+

    To improve legibility, these comments should be at least 2 spaces away @@ -1533,25 +1591,27 @@ from sound.effects import echo do) better than you do.

    - 
    +    
     # BAD COMMENT: Now go through the b array and make sure whenever i occurs
 # the next element is i+1
 
-
    
+

    -     - -

    Classes

    + + +
    +

    Classes

    ▶ - +
    If a class inherits from no other base classes, explicitly inherit from object. This also applies to nested classes. - -
    +
    - 
    Yes: class SampleClass(object):
+    
    Yes: class SampleClass(object):
          pass
 
 
@@ -1575,7 +1635,7 @@ from sound.effects import echo
      class ChildClass(ParentClass):
          """Explicitly inherits from another class already."""
 
-
    
+

    Inheriting from object is needed to make properties work properly, and it will protect your code from one particular potential @@ -1585,24 +1645,26 @@ from sound.effects import echo __getattribute__, __setattr__, __hash__, __repr__, and __str__.

    -     - -

    Strings

    +
    + +
    +

    Strings

    ▶ - +
    Use the % operator for formatting strings, even when the parameters are all strings. Use your best judgement to decide between + and % though. - -
    +

    Avoid using the + and += operators to @@ -1613,15 +1675,15 @@ from sound.effects import echo substring to a cStringIO.StringIO buffer).

    -
    No: employee_table = '<table>'
+
    No: employee_table = '<table>'
     for last_name, first_name in employee_list:
         employee_table += '<tr><td>%s, %s</td></tr>' % (last_name, first_name)
-    employee_table += '</table>'
    
-
    Yes: items = ['<table>']
+    employee_table += '</table>'
    
+
    Yes: items = ['<table>']
      for last_name, first_name in employee_list:
          items.append('<tr><td>%s, %s</td></tr>' % (last_name, first_name))
      items.append('</table>')
-     employee_table = ''.join(items)
    
+     employee_table = ''.join(items)

    Use """ for multi-line strings rather than @@ -1630,23 +1692,25 @@ from sound.effects import echo not flow with the indentation of the rest of the program:

    - 
      No:
+    
      No:
     print """This is pretty ugly.
 Don't do this.
 """
-
    
-
    Yes:
+
    
+
    Yes:
   print ("This is much nicer.\n"
-         "Do it this way.\n")
    
-      
-    
-    
    TODO Comments
    
+         "Do it this way.\n")
    + + +
    +

    TODO Comments

    ▶ - +
    Use TODO comments for code that is temporary, a short-term solution, or good-enough but not perfect. - -
    +
    +
    +
    +

    Imports formatting

    ▶ - +
    Imports should be on separate lines. - -
    +
    - - -

    Statements

    + +
    + +
    +

    Statements

    ▶ - +
    Generally only one statement per line. - -
    +
    +
    + +
    +

    Access Control

    ▶ - +
    If an accessor function would be trivial you should use public variables instead of accessor functions to avoid the extra cost of function calls in Python. When more functionality is added you can use property to keep the syntax consistent. - -
    +
    +
    +
    +

    Naming

    ▶ - +
    module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_VAR_NAME, instance_var_name, function_parameter_name, local_var_name. - -
    +
    +
    +
    +

    Main

    ▶ - +
    Even a file meant to be used as a script should be importable and a mere import should not have the side effect of executing the script's main functionality. The main functionality should be in a main() function. - -
    +

    All code at the top level will be executed when the module is @@ -1953,9 +2028,9 @@ Don't do this. perform other operations that should not be executed when the file is being pychecked or pydoced.

    - - - +
    + +

    Parting Words

    @@ -1983,7 +2058,7 @@ Don't do this.

    -Revision 2.14 +Revision 2.15

    diff --git a/styleguide.xsl b/styleguide.xsl index 488ac4c..197a05e 100644 --- a/styleguide.xsl +++ b/styleguide.xsl @@ -162,7 +162,7 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions"> - +

    @@ -175,11 +175,11 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">

    - +
    - +
    @@ -222,23 +222,22 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions"> - +
    - +
    - +
    - +
    -
    - +
    @@ -254,8 +253,8 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions"> - - +
    +
    @@ -293,9 +292,9 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">

    - TODO: +

    TODO: - +

    @@ -308,7 +307,7 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">     - + 
    
            
@@ -321,11 +320,11 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
    - +
    - + 
    
            
@@ -338,25 +337,25 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
    - +
    - +
    - +
    - +
    - +