Merge pull request #97 from MITx/pmitros/documentation

Coding standards document

doc/code_standards.txt

+Scope
+
+This document describes code quality standards for the i4x
+system. 
+
+1. Coding Standards
+
+Code falls into four categories:
+
+* Deployed. Running on a live server. 
+* Production. Intended for deployment. 
+* Scaffolding. Intended to define interfaces for future work, and
+  minimal implementations to support further development. 
+* Prototype. Experimental new features. 
+
+1.1 Deployed
+
+The standards for deployed code are identical to production. In
+general, we tend to do either:
+
+1) Perform a final verification QA cycle on changed parts of code
+before deploying.
+2) Use code on a staging or internal server for a week before
+deploying.
+
+1.2 Production
+
+All production code must be peer-reviewed. The code must meet the
+following standards:
+
+1) Test Suite. Code must have reasonable, although not complete, test
+   coverage.
+2) Consistent. Code must follow PEP8
+3) Clean Abstractions. 
+4) Future-Compatible. Code must not be incompatible with the
+   long-term vision of either the codebase or of edX. 
+5) Properly Documented
+6) Maintainable and deployable
+7) Robust. 
+
+All code paths must be manually or automatically verified. 
+
+1.3 Scaffolding
+
+All scaffolding code should be peer-reviewed. The code must meet the
+following standards:
+
+1) Testable. We do not require test coverage, but we do require the
+   code to be structured such that it is possible to build tests.
+2) Consistent. Code must follow PEP8
+3) Clean abstractions or obvious throw-away code. One of the goals 
+   of scaffolding is to define proper abstractions. 
+4) Future-Compatible. Code must not be incompatible with the
+   long-term vision of either the codebase or of edX. 
+5) Somewhat documented
+6) Unpluggable. There should be a setting to disable scaffolding code. 
+   By default, and by policy, it should never be enabled on production 
+   servers.
+7) Purpose. The scaffolding must provide a clean reason for existence
+   (e.g. define a specific interface, etc.)
+
+1.4 Prototype
+
+Prototype code should live in a separate branch. It should strive
+to follow PEP8, be readable, testable, and future-proof, but we have
+no hard standards. 
+
+2. Process Standards
+
+* Code should be integrated in small pull requests. Large commits
+  should be broken down into small commits for integration.
+* Every piece of production and deployed code must be reviewed prior
+  to integration.
+* Anyone on the edX team competent to review a piece of code may
+  review it (this may change as the team grows). 
+* Each contributor is responsible for finding a person to review their
+  code. If it is not clear to the contributor who is appropriate, each
+  project has an owner
+
+3. Documentation Standards
+
+* Whenever possible, documentation should live in code. 
+* When impossible, it should live in the github repo. 
+* Discussion should live on github, Basecamp or Pivotal, depending on
+  context.