Style Guide for Coding in yt
============================

Coding Style Guide
------------------

 * In general, follow PEP-8 guidelines.
   http://www.python.org/dev/peps/pep-0008/
 * Classes are ConjoinedCapitals, methods and functions are
   lowercase_with_underscores.
 * Use 4 spaces, not tabs, to represent indentation.
 * Line widths should not be more than 80 characters.
 * Do not use nested classes unless you have a very good reason to, such as
   requiring a namespace or class-definition modification.  Classes should live
   at the top level.  __metaclass__ is exempt from this.
 * Do not use unnecessary parenthesis in conditionals.  if((something) and
   (something_else)) should be rewritten as if something and something_else.
   Python is more forgiving than C.
 * Avoid copying memory when possible. For example, don't do 
   "a = a.reshape(3,4)" when "a.shape = (3,4)" will do, and "a = a * 3" should
   be "np.multiply(a, 3, a)".
 * In general, avoid all double-underscore method names: __something is usually
   unnecessary.
 * When writing a subclass, use the super built-in to access the super class,
   rather than explicitly. Ex: "super(SpecialGrid, self).__init__()" rather than
   "SpecialGrid.__init__()".
 * Doc strings should describe input, output, behavior, and any state changes
   that occur on an object.  See the file `doc/docstring_example.txt` for a
   fiducial example of a docstring.

API Guide
---------

 * Do not import "*" from anything other than "yt.funcs".
 * Internally, only import from source files directly -- instead of:

   from yt.visualization.api import ProjectionPlot

   do:

   from yt.visualization.plot_window import ProjectionPlot

 * Numpy is to be imported as "np", after a long time of using "na".
 * Do not use too many keyword arguments.  If you have a lot of keyword
   arguments, then you are doing too much in __init__ and not enough via
   parameter setting.
 * In function arguments, place spaces before commas.  def something(a,b,c)
   should be def something(a, b, c).
 * Don't create a new class to replicate the functionality of an old class --
   replace the old class.  Too many options makes for a confusing user
   experience.
 * Parameter files external to yt are a last resort.
 * The usage of the **kwargs construction should be avoided.  If they cannot
   be avoided, they must be explained, even if they are only to be passed on to
   a nested function.

Variable Names and Enzo-isms
----------------------------

 * Avoid Enzo-isms.  This includes but is not limited to:
   * Hard-coding parameter names that are the same as those in Enzo.  The
     following translation table should be of some help.  Note that the
     parameters are now properties on a Dataset subclass: you access them
     like ds.refine_by .
     * RefineBy => refine_by
     * TopGridRank => dimensionality
     * TopGridDimensions => domain_dimensions
     * InitialTime => current_time
     * DomainLeftEdge => domain_left_edge
     * DomainRightEdge => domain_right_edge
     * CurrentTimeIdentifier => unique_identifier
     * CosmologyCurrentRedshift => current_redshift
     * ComovingCoordinates => cosmological_simulation
     * CosmologyOmegaMatterNow => omega_matter
     * CosmologyOmegaLambdaNow => omega_lambda
     * CosmologyHubbleConstantNow => hubble_constant
   * Do not assume that the domain runs from 0 .. 1.  This is not true
     everywhere.
 * Variable names should be short but descriptive.
 * No globals!
