CodeConventions

Code Formatting Conventions

Practices and conventions for python source code

• Make sure code is consistent with python style guides: Style Guide || Style guide pep
• Try to limit external module dependencies to a minimal set (numpy, scipy, matplotlib, h5py and PIL can be assumed)

• GUI modules should be separated from the core library (ie no gui code in tdl/modules). GUIs (or other user interface type stuff) should be put into distinct locations such as: tdl/pds/pcgui or tdl/bobsgui etc...

• Put command line utilities and startup scripts in tdl/scripts

• Keep binary libs and the python wrappers in tdl/lib (and keep all the src code for the binaries in tdl/lib/src)

• Use all small letters for directory, file, function and variable names.

  • If necessary use '_' to make names more readable (ie my_cool_module.py)
  • Avoid non-alpha chars and spaces in names and paths.
  • Avoid using CamelHump or partialCapLetter notation except as noted below

• All classes should be named using CamelHump notation

• All class methods should use same rules as functions (small letters). Any methods that are 'private' should have a leading underscore (same is true for 'private' module functions and variables).

• Module (global) constants should be ALLCAPS
• Keep the length of a line of code (or comment) to less than 80chars
• Use 4 space indents (dont use tabs!)
• Add comments at the top of the module and after each def of a function, class and method.

Note that the partialCapLetter format is used throughout the xwGui code
(ie code in pds/pcgui).  This follows from the notation used in a lot
of wxApps.  So I think we can make an exception and allow the partialCapNotion
in the pds/pcgui directory but avoid it every where else!

---

Python Examples

• The header text at the top of a module

  """
  One liner
  
  Authors/Modifications:
  ----------------------
  Bob Jones
  
  Notes:
  ------
  Class to store and operate on stuff
  
  Examples:
  ---------
  * To create stuff
  >>stuff = new_stuff(1)
  
  Todo:
  ----
  * Add more stuff
  
  """
  

---

• Example doc string for a function:

  def calc_roi(dx=100,dy=100,shape=(195,487),cen=None):
      """
      Calculate an roi given a width, hieght and center
  
      Parameters:
      -----------
      * dx is the roi width (number of columns) in pixels
      * dy is the roi height (number of rows) in pixels
      * shape is the image shape (nrows,ncols)
      * cen is the tuple (r,c) for the central pixel.  If None
        then cen is calculated from the shape
  
      Returns:
      --------
      * [c1,r1,c2,r2] where c1/2,r1/2 are the
        column (x) and row (y) values defining the roi box.
  
      Examples:
      ---------
      >> r = calc_roi(dx=20,dy=50,shape=a.shape)
  
      """
  

---

• A class

  class MyClass:
      """
      Give a one line description like a fcn
  
      Then give more detailed info/notes
      which might fill a few lines
  
      Attributes
      ----------
      * A holds a list of things
      * T holds a string of something
  
      Examples
      --------
      >>a = MyClass(a=10)
      >>a.calc()
  
      """
      def __init__(self,a=None):
          """
          Initialize
  
          Parameters:
          -----------
          * a is the thing to get us going
          """
          self.A = a
  

---

Practices and conventions for C-source code

• Use ANSI C only. Use only standard clib functions (ie no external dependencies unless we really need them).
• Make a standard header in all source files
• Use small letters for directory names, file names, function names (and macros), and variable names. If needed use '_' to make the name more readable. Avoid numbers and other non-alpha chars. Avoid spaces in names and paths
• Header files should only include the definitions, function protoypes, data etc that you want to have accessible to other modules.
• All local definitions/prototypes should be given near the top of the source module (.c) just after the include statements.
• For a complicated module use leading underscores '_xx()' for function names of local functions.
• All structures should be named using CamelHump names
• If you define a new 'type' add a '_t' to the end of the name (my_type_t)
• Globals/constants should be ALLCAPS.
• Keep the length of a line of code to less than 80chars
• Use 4 space indents (dont use tabs!)
• Add comment before function

---

C Examples

• Example file header

  /******************************************************************************
  * Interface for generic some analysis
  *
  * Authors/modifications
  * ---------------------
  * - Bon Jones, 4-02-03
  *
  * Notes
  * -----
  * - Need some notes here on how to use this api
  *
  * Todo
  * ----
  * - Add more stuff
  ******************************************************************************/
  

---

• Example function definition

  /******************************************************************************
  * reflectivity()
  * Master function for computing x-ray reflectivity
  *
  * Arguments
  * ---------
  * - nlayer is the number of layers
  * - nelem is the number of elements
  *
  * Returns
  * -------
  * - 0 if successful, 1 if failed
  *
  * Notes
  * -----
  * - Some info about the function if needed
  ******************************************************************************/
  int reflectivity( int nlayer, int nelem)
  {
      int j, ret, fy_idx;
  }
  

---

• Example structure definition

  // define a structure FitData
  // then use typedef to make 'FitData_t'
  // a synonym for 'struct FitData'
  struct FitData {double *x;
                  double *y }
  typedef struct FitData FitData_t
  

---