# HG changeset patch # User Matthew Turk # Date 1283208066 25200 # Branch yt # Node ID 619e237aba6d3b7a7bf3de6135b592afcb388492 # Parent 01ad66fba7460d8ea6c5173f17f78bf9030412b1 Updating coding style guide and adding a brief bit about how to develop yt. diff -r 01ad66fba7460d8ea6c5173f17f78bf9030412b1 -r 619e237aba6d3b7a7bf3de6135b592afcb388492 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 01ad66fba7460d8ea6c5173f17f78bf9030412b1 -r 619e237aba6d3b7a7bf3de6135b592afcb388492 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@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.