wiki:TCTPythonCodingStandardsChanges
Last modified 8 years ago Last modified on 10/05/2010 04:01:04 PM

TCT Python Coding Standards Changes from the original Release

This document highlights the substantive changes made to the Python 
Standards Doc during its first revision pass.  The old and replacement
text blocks are provided to enable comparison.

However, since the first editing in 2009, many more changes were 
made in order to make the document:
  * more readable;
  * to conform to the C++ Std layout;
  * to highlight the stringency levels of each rule.

The entire document now needs to be reviewed since the explicit 
addition of the stringency level on each Rule might have changed 
the original intent of the founding fathers.

After the document has been reviewed and the Rules anchored, numbers
will be assigned to each python rule so that reports can more easily 
identify a deviation.



Following are the first set of editing changes made to the document. 
They are labeled with Old (original text) or New (revised or added text).
View the document on-line since the text blocks are truncated when 
printed but horizontally scrollable when displayed.
NEW:
 	45	==== Maximum Line Length ==== 
 	46	 
 	47	 * Limit all lines to a maximum of 110 characters. 

REMOVED:
 	48	   * There are still many devices around that are limited to 80 character lines; plus, limiting windows to 80 characters makes it possible to have several windows side-by-side. The default wrapping on such devices looks ugly. 
 	49	 
 
OLD:
105	86	=== Code Order === 
106	87	 
107	 	Each module should start with the following, in order: 
108	 	* A module doc string. 
109	 	* Import statements, followed by a blank line. 
110	 	* The __all__ statement, if any, followed by a blank line 
111	 	* Module-wide global variables and constants, if any, followed by a blank line. 


NEW:
 	88	Within a module the things should be placed in the following order: 
 	89	{{{ 
 	90	   1. Shebang line (#!), only for executable scripts 
 	91	   2. Module-level comments 
 	92	   3. Module-level docstring 
 	93	   4. Imports 
 	94	   5. '__all__' statement, if any 
 	95	   6. Module variables (names start with underscore) 
 	96	   7. Module functions and classes (names start with underscore) 
 	97	   8. Public variables 
 	98	   9. Public functions and classes 
 	99	   10. Optional test suites 
 	100	}}} 


NEW:
 	138	 * Consistency with the [http://dev.lsstcorp.org/trac/wiki/C%2B%2BStandard LSST C++ Coding Standards] namespaces exists. 
 	139	   * Good  
 	140	      * "from lsst.foo.bar import myFunction" is analogous to "using lsst::foo::bar::myFunction 
 	141	      * "import lsst.foo.bar as fooBar" is analogous to "namespace fooBar = lsst::foo::bar" 
 	142	   * '''Disallowed''' in both Coding Standards - except in '''!__init!__.py''' library initialization context. 
 	143	      * "from lsst.foo.bar import *" is analogous to "using namespace lsst::foo::bar" 
151	144	 

Revision to bring into C++ conformity
	 
OLD:

348	326	=== Naming Conventions === 
349	327	 
350	 	* Names to Avoid 
351	 	 
352	 	Never use the characters `l' (lowercase letter el), `O' (uppercase 
353	 	letter oh), or `I' (uppercase letter eye) as single character variable 
354	 	names. In some fonts, these characters are indistinguishable from the numerals 
355	 	one and zero. When tempted to use `l', use `L' instead. 
356	 	 
357	 	* Module and Package Names 
358	 	 
359	 	Modules should have short, lowercase names, without underscores. 
360	 	 
361	 	When an extension module written in C or C++ has an accompanying Python 
362	 	module that provides a higher level (e.g. more object oriented) 
363	 	interface, the C/C++ module has a leading underscore (e.g. _socket). 
364	 	 
365	 	Module names are mapped to file names, so always assume a case-sensitive file system and use the case that matches the file name in import statements. 
366	 	 
367	 	* Class Names 
368	 	 
369	 	Use capitalized "camel case" (words are joined without spaces, and each inner word is capitalized). In addition, use a leading underscore for classes for internal use. 
370	 	 
371	 	* Exception Names 
372	 	 
373	 	Use the class name convention (since exceptions are classes). In addition, use the suffix "Error" on your 
NEW:
 	328	The naming conventions for LSST Python and C++ source have been defined to be as similar as the respective languages allow. 
 	329	 
 	330	==== General Remarks ==== 
 	331	In general, class names are !CamelCase with leading uppercase; all other names in the source are camelCase with leading lowercase, except for module variables used as module global constants - which should be UPPERCASE_WITH_UNDERSCORES. 
 	332	 
 	333	Names may be decorated with leading and/or trailing underscores in the following instances 
 	334	 * Names with double leading and trailing underscores are "magic" names (e.g. '''!__init!__, !__name!__''', or '''!__str!__'''). Users should not use this form to define "user names". 
 	335	 * Names with leading double underscores (but without trailing double underscores) define class-private names if they appear inside class. 
 	336	 * Single leading underscore  is the weak "internal use" indicator. E.g. "from M import *" does not import names starting with an underscore. Modules that are designed for use via "from M import *" should use the '''!__all!__''' mechanism to prevent exporting globals and/or the weak "internal use" indicator. 
 	337	 * Single trailing underscore is used to prevent name clash with reserved keyword; or better, yet, choose a synonym to avoid the clash. 
 	338	 
 	339	 
 	340	The names of files containing Python source should be camelCase with leading lowercase letter and terminating with '''.py'''. 
 	341	 
 	342	==== Class Names ==== 
 	343	 
 	344	Python class names should follow the same conventions as C++ class names - they should be CamelCase with leading uppercase. Typically there should be one class in one source file. As an exception you can put one or more "hidden" classes (whose names start with underscore) along with the normal class if these hidden classes' names are never exposed to the outside world. 
 	345	 
 	346	==== Exception Names ==== 
 	347	 
 	348	Use the class name convention since exceptions are classes. In addition, use the suffix "Error" on your 
374	349	exception names (if the exception actually is an error). 
375	350	

OLD: 
376	 	* Global Variable Names 
377	 	 
378	 	(Let's hope that these variables are meant for use inside one module 
379	 	only.)  The conventions are about the same as those for functions. 
380	 	 
381	 	Modules that are designed for use via "from M import *" should use the 
382	 	__all__ mechanism to prevent exporting globals and/or use the the older 
383	 	convention of prefixing such globals with an underscore (which you might 
384	 	want to do to indicate these globals are "module non-public"). 
385	 	 
386	 	* Function Names 
387	 	 
388	 	Use camelCase. 
389	 	 
390	 	Use one leading underscore for non-public function names. 
391	 	 
392	 	* Function and method arguments 
NEW:
 	351	==== Method and Attribute Names ==== 
 	352	 
 	353	Class and object methods and attributes should be made camelCase, with leading lowercase. To make attribute or method private, prefix it with double underscore. There is no reason to prefix member variables with single underscore in Python because they are always referenced through 'self'. 
 	354	 
 	355	Module methods (free functions) should be camelCase with leading lowercase. Modules should not normally expose their variables directly, except the variables which are "constants". Constants should be named in UPPERCASE_WITH_UNDERSCORES. Module variables of functions which should not be exposed start with underscore. 
 	356	 
 	357	==== Module Names ==== 
 	358	 
 	359	Modules which contain class definitions should be named after the class name (one module per class). Modules containing only functions should be named in camelCase with leading lowercase.  
 	360	 
 	361	When an extension module written in C or C++ has an accompanying Python module that provides a higher level (e.g. more object oriented) interface, the C/C++ module has a leading underscore (e.g. _socket). 
 	362	 
 	363	Modules that are designed for use via "from M import *" should use the '''!__all!__''' mechanism to prevent exporting globals and/or use the the older convention of prefixing such globals with an underscore to indicate these globals are "module non-public". 
 	364	 
 	365	==== Python Source File Names ==== 
 	366	 
 	367	The name of the file containing a module will be the camelCase-with-leading-lowercase transliteration of the module name. 
 	368	 
 	369	The name of an executable python script will be camelCase with leading lowercase. The name of a test case should be descriptive without the need for a trailing numeral to distinguish one test case from another; the name will be camelCase with leading lowercase. 
 	370	 
 	371
 	372	==== Function and method arguments ==== 
393	373	 
394	374	Always use 'self' for the first argument to instance methods. 
… 	… 	 
396	376	Always use 'cls' for the first argument to class methods. 
397	377	 
398	 	If a function argument's name clashes with a reserved keyword, it is 
399	 	generally better to append a single trailing underscore rather than use 
400	 	an abbreviation or spelling corruption. Thus "print_" is better than 
401	 	"prnt". (Perhaps better is to avoid such clashes by using a synonym.) 
402	 	 
403	 	* Method Names and Instance Variables 
404	 	 
405	 	Use camelCase. 
406	 	 
407	 	Use one leading underscore only for non-public methods and instance variables. 
408	 	 
409	 	To avoid name clashes with subclasses, use two leading underscores to 
410	 	invoke Python's name mangling rules. 
411	 	 
412	 	 Python mangles these names with the class name: if class Foo has an 
413	 	 attribute named {{{__a}}}, it cannot be accessed by {{{Foo.__a}}}. (An insistent 
414	 	 user could still gain access by calling {{{Foo._Foo__a}}}.)  Generally, double 
415	 	 leading underscores should be used only to avoid name conflicts with 
416	 	 attributes in classes designed to be subclassed. 
417	 	 
418	 	 Note: there is some controversy about the use of {{{__}}}names (see below). 
419	 	 
420	 	 Names that start and end with {{{__}}} (two underscores), such as {{{__init__}}} and {{{__str__}}}, are reserved. Only use such names for their standard, documented purpose. Never invent your own such names. 
421	 	 
NEW:
 	378	==== Names to Avoid ==== 
 	379	 
 	380	Never use the characters  
 	381	 * 'l' (lowercase letter el),  
 	382	 * 'O' (uppercase letter oh), or  
 	383	 * 'I' (uppercase letter eye) as single character variable names.  
 	384	In some fonts, these characters are indistinguishable from the numerals one and zero. When tempted to use 'l', use 'L' instead. 
 	385	 
 	386	 
 	387