StyleGuide.txt

 PyMS coding Style Guide
 =======================

 [The basis for this document was PEP-8 "Style Guide for Python Code", by
 Guido van Rossum and Barry Warsaw]

1. General

  1.1 Indentation. Use 4 spaces per indentation level. Do not use tabs.

  1.2 Line lenght. Limit all lines to a maximum of 80 characters.  Long lines
    should be wrapped with implied line continuation if inside parentheses,
    or explicitly using a backslash. Indent the continued line for 8
    spaces to distinguish from the normal 4 spaces for one indentation
    level.

  1.3 Whitespaces. Use tight parentheses, brackets or braces, as in:
    spam(ham[1],{eggs:2}). Use only one space around binary operators
    (assignment (=), comparisons (==, <, >, !=, <>, <=, >=, in, not in, is,
    is not), and boolean operators (and, or, not)

    Do not use whitespace after an expression, or immediately before a comma,
    semicolon, or colon. For example, do no not write:
    if x == 4 : print x , y ; x , y = y , x
    Instead write this as:
    if x == 4: print x, y; x, y = y, x

    In complex expressions do not insert spaces around arithmetic operators
    on the first level, but do insert a single space on the second level to
    improve readability. For example:
    i = i+1
    x = x*2 - 1

  1.4 Grouping commandsa and using newlines. Organise commands into logical
    groups, and separate if necessary with newlines to improve readability.

    Example:

        # -- snip --
        if not is_str(file_name):
            error("'file_name' must be a string")

        try:
            file = CDF(file_name)
            self.__file_name = file_name
            self.__file_handle = file
        except CDFError:
            error("Cannot open file '%s'" % file_name) 

        print " -> Processing netCDF file '%s'" % (self.__file_name)

        self.__set_min_max_mass(file)
        self.__set_intensity_list(file)
        # -- snip --

    In block statements (such as for loops and if statements), do not use the blank
    line in a single group of statements; use one blank line to separate if the
    block contains more than one group of statements.

    Examples:

        # -- snip --
        td_list = []
        for ii in range(len(time_list)-1):
            td = time_list[ii+1]-time_list[ii]
            td_list.append(td)
        # -- snip --

        # -- snip ---
        if len(time_list) > len(intensity_matrix):

            self.set_scan_index()
            scan_index_list = self.__scan_index_list

            count = 0
            while len(intensity_matrix) < len(time_list):
                count = count + 1
                scan = numpy.repeat([0], max_mass - min_mass + 1)
                intensity_matrix.insert(0,scan)
        # -- snip --- 

  1.5 File pointers. Use 'fp' for file pointer variables. If simultaneous
    use of two or more file pointers is required, use 'fp1', 'fp2', etc.

    Example:

        fp1 = open('some_file.txt','w')
        fp2 = open('another.txt','w')

2. Imports

  2.1 Grouping. Group imports as:

    1) Standard library imports
    2) External module imports
    3) Other PyMS subpackage imports
    4) This subpackage imports

    Separate each group by a blank line.

  2.2 Import forms

    - For standard library modules, always import the entire module
      name space. i.e.

      import os
      ...
      os.path()

    - For PyMS modules always import specific functions, i.e.

      from pyms.Utils.Utils import is_str, is_int 

3. Comments

  3.1 Comments should be complete sentences.  If a comment is a phrase
    or sentence, its first word should be capitalized, unless it is
    an identifier that begins with a lower case letter.

  3.2 If a comment is short, the period at the end is best omitted.
    Longer comments of block comments generally consist of one or
    more paragraphs built out of complete sentences, and each sentence
    should end with a period.

  3.3 Block comments generally apply to some (or all) code that follows
    them, and are indented to the same level as that code.  Each line
    of a block comment starts with a # and a single space (unless it
    is indented text inside the comment).  Paragraphs inside a block
    comment are separated by a line containing a single #.  Block
    comments should be surrounded by a blank line above and below them.

  3.4 An inline comment is a comment on the same line as a statement.
    Inline comments should be separated by a two spaces from the
    statement, and should start with a # and a single space. Use
    sparingly.

4. Naming Styles

  4.1 Variable names

    - Global variable names should be prefixed with an underscore
      to prevent their export from the module.

    - Specific variable names:

      - Use 'file_name' instead of 'filename'
      - Use 'fp' for file pointer, i.e. fp = open(file_name, 'r')

  4.2 Module names.  Module names should be short, starting with an
      uppercase letter (i.e. Utils.py).

  4.2 Class names.  Class names use the CapWords convention. Classes for
      internal use have a leading underscore in addition.

  4.4 Exception Names. Exceptions should be handled via the function
      pyms.Utils.Error.error() 

  4.5 Function names should be lowercase, with words separated by
      underscores where suitable to improve readability. 

  4.6 Method Names names should follow the same principles as the function
      names.

  4.7 Internal methods and instance variables. Use one leading underscore
      only for internal methods and instance variables which are not
      intended to be part of the class's public interface.

  4.8 Class-private names. Use two leading underscores to denote
      class-private names, this includes class-private methods (eg.
      __privfunc()). Note: Python "mangles" these names with the
      class name: if class Foo has an attribute named __a, it cannot
      be accessed by Foo.__a. (it still could be accessed by calling
      Foo._Foo__a.)

  4.9 Private/public class attributes. Public attributes should have
      no leading or trailing underscores. Private attributes should
      have two leading underscores, no trailing underscores. Non-public
      attributes should have a single leading underscore, no trailing
      underscores (the difference between private and non-public is that
      the former will never be useful for a derived class, while the
      latter might be).

  4.10 Reminder: Python names with specific meanings

    - _single_leading_underscore: weak "internal use" indicator (e.g.
     "from M import *" does not import objects whose name starts with
     an underscore).

    - single_trailing_underscore_: used by convention to avoid conflicts
      with Python keyword, "Tkinter.Toplevel(master, class_='ClassName')".

    - __double_leading_underscore: class-private names as of Python 1.4.

    - __double_leading_and_trailing_underscore__: "magic" objects or
      attributes that live in user-controlled namespaces, e.g. __init__,
      __import__ or __file__.

5. Docstrings

  5.1 General

    - All sub-packages, modules, functions, and classes must have proper
      epydoc docstrings

    - When designating types for @type and @rtype, use the official names
      from the 'types' package i.e. BooleanType, StringType, FileType etc.

    - All docstrings must start with a single summary sentence conciely
      describing the function, and this sentence must not be terminated
      by a period. Additional description may follow in the form of
      multi-senteced paragraphs, separated by a blank line from the
      summary sentence

    - Leave one blank line above and below the docstring

    - Separate @summary, @param/@type, @return/@rtype, @author strings
      with one blank line (see the example in 5.4)

  5.2 Packages

    - Package doctrings are defined in __init__.py. This example shows
      top three lines of pyms.__input__.py:

    Examples:

      """
      The root of the package pyms
      """

  5.3 Modules

    - A summary for the module should be written concisely in a single
      sentence, enclosed above and below with lines containint only """

    Examples:

      """
      Provides general I/O functions
      """

  5.4 Functions

    - In all functions the following epydoc tags must be defined:
      @summary, @param, @type (for all input arguments), and @return,
      @rtype, and @author. Other epytext fields are optional.

    - If the function does not return a value, @return is None and
      @rtype is NoneType

    Examples:

      def open_for_reading(file_name):

          """
          @summary: Opens file for reading, returns file pointer

          @param file_name: Name of the file to be opened for reading
          @type file_name: StringType

          @return: Pointer to the opened file
          @rtype: FileType

          @author: Jake Blues 
          """

  5.5 Classes

    - The root class docstring must contain @summary and @author fields

    - The __init__ method must contain @param and @type fields. Other
      fields are optional.

    - Methods docstrings adhere to rules 5.4 for Functions. Except for
      special methods (i.e. __len__(), __del__(), etc) which should
      contain only the @summary field, and possibly the @author field.

    - Class methods. The rules for functions apply, except that the tag
      @author does not need to be defined (if authors are given in the
      class docstring).

    Examples:

      class ChemStation:

          """
          @summary: ANDI-MS reader for Agilent ChemStation NetCDF files

          @author: Jake Blues
          """

          def __init__(self, file_name):

              """
              @param file_name: The name of the ANDI-MS file
              @type file_name: StringType
              """ 


 PyMS "User Guide" Style Guide
 =============================

1. General

  1.1 Reference labels.

    - In reference labels use strings with words separated
    by hyphen. Examples:

        \label{sec:time-string}
        \label{sec:display-tic}
        \label{fig:71-spec} 

 1.2 Refernce labels for sections, subsections, and figures
    should be preceeded with a tag:

        sections: 'sec:'
        subsections: 'subsec:'
        figures: 'fig:'

   Examples:
        
        \label{sec:time-string}
        \label{subsec:numpy}
        \label{fig:71-spec} 

2. Figures

  2.1 Captions. All Figures must have figure captions. The last
  sentence in Figure captions should not end with a fullstop.
  Example:

  \begin{figure}
   \begin{center}
    \includegraphics[scale=0.33]{graphics/chapter07/test-70a.eps}
   \end{center}
   \caption{Graphics window displayed by the script 70a/proc.py}
   \label{fig:70a}
  \end{figure}