draft of coding guidelines

CODESTYLE.md

@@ -0,0 +1,68 @@
+Generally
+=========
+
+Use use regular coding style:
+http://www.python.org/dev/peps/pep-0008/
+http://google-styleguide.googlecode.com/
+
+One can break those rules if the situation requires it. Keep it contained.
+
+
+Some specific rules for this package :
+
+Git
+===
+
+This project use git-flow {nvie.com/posts/a-successful-git-branching-model}
+as a model for branches management. In particular :
+- master is for release only
+- when you commit to develop, run nosetests before. All tests should pass.
+- in feature/branches, you do whatever you want.
+- when developping a new feature, write tests for it.
+
+
+Alignement
+==========
+
+We strive for code clarity first, and then conformance to pep-8.
+As such, any code alignement that make the code clearer, easier to use,
+edit and debug takes precedence over proper spacing.
+
+
+Strings
+=======
+
+For literals strings, ' is preferred to ", but use " when the string contains '.
+
+yes: "run the command 'flake8' before committing"
+no : 'run the command \'flake8\' before committing'
+
+
+Use '.format' syntax for strings, and '+' only when the use calls it.
+Don't mix and match.
+
+yes: s = color + s + end
+yes: '{}: file {} could not be read'.format(errorname, filepath)
+no : errorname + ': file {} could not be read'.format(filepath)
+
+
+Names
+=====
+
+Avoid at all cost to name a variable like a module from the package, a
+dependency or the standart lib.
+This breaks coherence across the code, makes it harder to read.
+Change either the module or variable name, I don't care.
+
+
+Function that have only local uses should be preceded by an underscore.
+
+yes: def _auxiliary_local_fun():
+         pass
+no : def auxiliary_local_fun():
+         pass
+
+These functiona won't be imported automatically with the module.
+It keeps the interface clean, makes occasional hacks explicit, and inform other
+developers that theses functions may need special care when uses outside their
+natural habitat.