554e718550190e75821cf585f6123ee55bd3d551
vsmalladi
  Tue Apr 24 11:42:04 2012 -0700
Added guidlines for length's of modules, functions and methods. Redmine #7162.
diff --git python/style.txt python/style.txt
index ce89a67..0f138f6 100644
--- python/style.txt
+++ python/style.txt
@@ -1,210 +1,216 @@
 Style Guide for Python Code
 
 CODE CONVENTIONS
 
 Follow the Python coding conventions laid out by the Python Style guide, except for the 
 UCSC Genomics Group specific conventions outlined below. 
     http://www.python.org/dev/peps/pep-0008/
 
 INDENTATION AND SPACING
 
 Each block of code is indented by 4 spaces from the previous block. Do not use
 tabs to separate blocks of code. The indentation convention differs from the C coding style
 found in src/README, which uses 4-base indents/8-base tabs. Common editor configurations 
 for disallowing tabs are:
     
     vim:
         Add "set expandtab" to .vimrc
 
     emacs:
         Add "(setq-default indent-tabs-mode nil)" to .emacs
 
 Lines are no more than 100 characters wide.
 
 INTERPRETER DIRECTIVE
 
 The first line of any UCSC Python script should be:
     #!/usr/bin/env python2.7
 
 This line will invoke python2.7 found in the user's PATH. It ensures that scripts developed 
 by UCSC can be distributed and explicitly states which Python version was used to develop the scripts.
      
 NAMING CONVENTIONS
 
 Use mixedCase for symbol names: the leading character is not capitalized and all
 successive words are capitalized. (Classes are an exception, see below.) Non-UCSC
 Python code may follow other conventions and does not need to be adapted to
 these naming conventions.   
 
 Abbreviations follow rules in src/README:
 
     Abbreviation of words is strongly discouraged.  Words of five letters and less should 
     generally not be abbreviated. If a word is abbreviated in general it is abbreviated 
     to the first three letters:
        tabSeparatedFile -> tabSepFile
     In some cases, for local variables abbreviating to a single letter for each word is okay:
        tabSeparatedFile -> tsf
     In complex cases you may treat the abbreviation itself as a word, and only the
     first letter is capitalized:
        genscanTabSeparatedFile -> genscanTsf
     Numbers are considered words.  You would represent "chromosome 22 annotations"
     as "chromosome22Annotations" or "chr22Ann." Note the capitalized 'A" after the 22.
 
 
 Packages and Modules
 
 In Python, a package is represented as a directory with an __init__.py file in it, 
 and contains some number of modules, which are represented as files with a .py extension.
 A module may in turn contain any number of related classes and methods. This differs from Java,
 where one file correlates to one class: in Python it is correct to treat one module similar to
 a whole namespace in Java.
 
+In general try to keep modules on the order of 100's of lines.
+
 Internal packages and modules should have short names in mixedCase, with no spaces or underscores.
 A good example of this style is the ucscGenomics package:
 
     ucscGenomics/
         __init__.py
         ra.py
         cv.py
         ...
 
     For more information:
         http://docs.python.org/tutorial/modules.html
 
 Imports
 
 The most correct way to import something in Python is by specifying its containing module:
     import os
     from ucscGenomics import ra
  
     Then, the qualified name can be used:
         someRa = ra.RaFile()
    
     Do not import as below, as this may cause local naming conflicts:
         from ucscGenomics.ra import RaFile
         from ucscGenomics.track import *
 
 Imports should follow the structure:
         
     1. Each import should be on a separate line, unless modules are from the same package:
         import os
         import sys
 
         from ucscGenomics import ra, track, qa
        
     2. Imports should be at the top of the file. Each section should be separated by a blank line:
 
         a. standard library imports
 
         b. third party package/module imports
 
         c. local package/module imports
 
 For more information, see the "Imports" section:
     http://www.python.org/dev/peps/pep-0008/
 
 Classes
 
 CapitalCase names. Note the leading capital letter to distinguish between a ClassName and 
 a functionName. Underscores are not used, except for private internal classes, 
 where the name is preceded by double underscores which Python recognizes as private.
 
 Methods
 
 mixedCase names. The leading character is not capitalized, but all successive words are 
 capitalized. Underscores are not used, except for private internal methods, 
 where the name is preceded by double underscores which Python recognizes as private.
 
+In general try to keep methods around 20 lines.
+
 Functions
 
 mixedCase names. The leading character is not capitalized, but all 
 successive words are capitalized.
 
+In general try to keep methods around 20 lines.
+
 Variables
 
 mixedCase names. Underscores are not used, except for private internal variables, 
 where the name is preceded by double underscores which Python recognizes as private.
 
 COMMENTING
 
 Note: Still working out which automation document tool to use.
 
 Automated documentation is carried out using the Epydoc tool:
     http://epydoc.sourceforge.net/
 
 Comments should follow the conventions:
 
     1. Every module should have a paragraph at the beginning. Single class modules may 
         omit paragraph in favor of class comment.
 
     2. Use Python's docstring convention to embed comments, using """triple double quotes""":
        http://www.python.org/dev/peps/pep-0257/
 
     3. Use Epytext markup language conventions when commenting:
         http://epydoc.sourceforge.net/epytext.html
 
     4. Use Epytext field tags to describe specific properties of objects:
 
         Structure:
 
             a. Fields must be placed at the end of a docstring.
 
             b. Each field is distinguished by the following pattern:
                 @tag: body
                 @tag arg: body
 
             c. All blocks pertaining to a field must have equal indentation
                greater than or equal to field tag indentation.  
 
             d. Optional field tags to use:
 
                 i.  @param - Description of parameter to a function
 
                 ii. @return - Description of a function's return value 
                         
                 def exampleFunction():
                     """
                     This paragraph describes the object.
 
                     @param inputFile: Input file name
     
                     @return: This is a description of the function's return value
                     """ 
                 
         For more information and supported fields, see:
             http://epydoc.sourceforge.net/fields.html#fields
 
 TESTING
 
 Testing is carried out using the unittest module in Python:
     http://docs.python.org/library/unittest.html
 
 This module allows for self-running scripts, which are self-contained and should provide
 their own input and output directories and files. The scripts themselves are composed of 
 one or more classes, all of which inherit from unittest.TestCase and contain one or more 
 methods which use various asserts or failure checks to determine whether a test passes or not.
 
     Structure:
 
         1. At the start of a script import unittest module:
             import unittest
 
         2. A test case is created as a sub-class of unittest.TestCase:
             class TestSomeFunctions(unittest.TestCase):
 
         3. Test method names should begin with 'test' so that the test runner is 
            aware of which methods are tests:
             def testSomeSpecificFuntion(self):
 
         4. Define a setUp method to run prior to start of each test.
             def setUp(self):
 
         5. Define a tearDown method to run after each test.
             def tearDown(self):
 
         6. To invoke tests with a simple command-line interface add the following lines:
             if __name__ == '__main__':
                 unittest.main()
            
     For other ways to run tests see:
                 http://docs.python.org/library/unittest.html