[Yt-svn] yt: Updating coding style guide and adding a brief bit about how...
hg at spacepope.org
hg at spacepope.org
Mon Aug 30 15:41:29 PDT 2010
hg Repository: yt
details: yt/rev/619e237aba6d
changeset: 3358:619e237aba6d
user: Matthew Turk <matthewturk at gmail.com>
date:
Mon Aug 30 15:41:06 2010 -0700
description:
Updating coding style guide and adding a brief bit about how to develop yt.
diffstat:
doc/coding_styleguide.txt | 73 +++++++++++++++++++-----
doc/how_to_develop_yt.txt | 146 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 203 insertions(+), 16 deletions(-)
diffs (248 lines):
diff -r 01ad66fba746 -r 619e237aba6d doc/coding_styleguide.txt
--- a/doc/coding_styleguide.txt Mon Aug 30 14:26:22 2010 -0700
+++ b/doc/coding_styleguide.txt Mon Aug 30 15:41:06 2010 -0700
@@ -1,37 +1,78 @@
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.
- * Avoid at all costs importing "*" from a function or a module unless that
- module is "yt.funcs" or "yt.arraytypes". "yt.mods" may be a special case,
- but if at all possible avoid importing it.
+ * 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 unecessary 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 "na.multiply(a, 3, a)".
+ * In general, avoid all double-underscore method names: __something is usually
+ unnecessary.
+ * 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 PlotCollection
+
+ do:
+
+ from yt.visualization.plot_collection import PlotCollection
+
* Numpy is to be imported as "na" not "np". While this may change in the
future, for now this is the correct idiom.
* 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.
- * Line widths should not be more than 80 characters.
- * Do not use unecessary parenthesis in conditionals. if((something) and
- (something_else)) should be rewritten as if something and something_else.
- Python is more forgiving than C.
* In function arguments, place spaces before commas. def something(a,b,c)
should be def something(a, b, c).
- * 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.
* 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 are a last resort.
- * 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 "na.multiply(a, 3, a)".
* The usage of the **kwargs construction should be avoided. If they cannoted
be avoided, they must be explained, even if they are only to be passed on to
a nested function.
- * 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.
+
+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 StaticOutput subclass: you access them
+ like pf.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!
diff -r 01ad66fba746 -r 619e237aba6d doc/how_to_develop_yt.txt
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/how_to_develop_yt.txt Mon Aug 30 15:41:06 2010 -0700
@@ -0,0 +1,146 @@
+How To Develop yt
+=================
+
+We are very happy to accept patches, features, and bugfixes from any member of
+the community! yt is developed using mercurial, primarily because it enables
+very easy and straightforward submission of changesets. We're eager to hear
+from you, and if you are developing yt, we encourage you to subscribe to the
+developer mailing list:
+
+http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
+
+Please feel free to hack around, commit changes, and send them upstream. If
+you're new to Mercurial, these three resources are pretty great for learning
+the ins and outs:
+
+ * http://hginit.com
+ * http://hgbook.red-bean.com/read/
+ * http://mercurial.selenic.com/
+
+Keep in touch, and happy hacking! We also provide doc/coding_styleguide.txt
+and an example of a fiducial docstring in doc/docstring_example.txt. Please
+read them before hacking on the codebase, and feel free to email any of the
+mailing lists for help with the codebase.
+
+Licenses
+--------
+
+All code in yt should be under the GPL-3 (preferred) or a compatible license.
+
+How To Get The Source Code
+--------------------------
+
+With the yt installation script you should have a copy of Mercurial. You can
+clone the repository like so:
+
+ $ hg clone http://hg.enzotools.org/yt/
+
+You can update to any branch or revision by executing the command:
+
+ $ hg up -C some_revision_specifier
+
+Specifying a branch name in the revspec will update to the latest revision on
+that branch. If you ran the installation script, you can tell Python to use a
+different version of the library by executing:
+
+ $ python2.6 setup.py develop
+
+This will rebuild all C modules as well.
+
+How To Read The Source Code
+---------------------------
+
+yt is organized into several sub-packages, each of which governs a different
+conceptual regime.
+
+ frontends
+ This is where interfaces to codes are created. Within each subdirectory of
+ yt/frontends/ there must exist the following files, even if empty:
+
+ * data_structures.py, where subclasses of AMRGridPatch, StaticOutput and
+ AMRHierarchy are defined.
+ * io.py, where a subclass of IOHandler is defined.
+ * misc.py, where any miscellaneous functions or classes are defined.
+ * definitions.py, where any definitions specific to the frontend are
+ defined. (i.e., header formats, etc.)
+
+ visualization
+ This is where all visualization modules are stored. This includes plot
+ collections, the volume rendering interface, and pixelization frontends.
+
+ data_objects
+ All objects that handle data, processed or unprocessed, not explicitly
+ defined as visualization are located in here. This includes the base
+ classes for data regions, covering grids, time series, and so on. This
+ also includes derived fields and derived quantities.
+
+ analysis_modules
+ This is where all mechanisms for processing data live. This includes
+ things like clump finding, halo profiling, halo finding, and so on. This
+ is something of a catchall, but it serves as a level of greater
+ abstraction that simply data selection and modification.
+
+ gui
+ This is where all GUI components go. Typically this will be some small
+ tool used for one or two things, which contains a launching mechanism on
+ the command line.
+
+ utilities
+ All broadly useful code that doesn't clearly fit in one of the other
+ categories goes here.
+
+How To Use Branching
+--------------------
+
+If you are planning on making a large change to the code base that may not be
+ready for many commits, or if you are planning on breaking some functionality
+and rewriting it, you are encouraged to create a new named branch. You can
+mark the current repository as a new named branch by executing:
+
+ $ hg branch new_feature_name
+
+The next commit and all subsequent commits will be contained within that named
+branch. At this point, add your branch here:
+
+http://yt.enzotools.org/wiki/ExistingBranches
+
+To merge changes in from another branch, you would execute:
+
+ $ hg merge some_other_branch
+
+Note also that you can use revision specifiers instead of "some_other_branch".
+When you are ready to merge back into the main branch, execute this process:
+
+ $ hg merge name_of_main_branch
+ $ hg commit --close-branch
+ $ hg up -C name_of_main_branch
+ $ hg merge name_of_feature_branch
+ $ hg commit
+
+When you execute the merge you may have to resolve conflicts. Once you resolve
+conflicts in a file, you can mark it as resolved by doing:
+
+ $ hg resolve -m path/to/conflicting/file.py
+
+Please be careful when resolving conflicts in files.
+
+Once your branch has been merged in, mark it as closed on the wiki page.
+
+How To Submit Changes
+---------------------
+
+If you do not have "push" rights on the primary mercurial repository, set up
+and use the "patchbomb" extension in mercurial to email a bundle of changes to
+the developer mailing list, yt-dev at lists.spacepope.org .
+
+The patchbomb extension is documented here:
+
+http://mercurial.selenic.com/wiki/PatchbombExtension
+
+Please be sure to specify that you wish to send a bundle. This can be
+accomplished by setting up your hgrc to email the yt-dev mailing list and
+executing the command:
+
+ $ hg email -b
+
+Be sure to read the output of "hg help email" before doing this.
More information about the yt-svn
mailing list