From 0f8d2021e793acb408f5c33c51865246c2a7b98c Mon Sep 17 00:00:00 2001 From: Piotr Mitros Date: Mon, 11 Jun 2012 15:38:19 -0400 Subject: [PATCH] Documentation Standards --- doc/code_standards.txt | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/doc/code_standards.txt b/doc/code_standards.txt index 84180d3d7e..02953b3677 100644 --- a/doc/code_standards.txt +++ b/doc/code_standards.txt @@ -30,12 +30,12 @@ following standards: 1) Test Suite. Code must have reasonable, although not complete, test coverage. -2) Consistency. Code must follow PEP8 +2) Consistent. Code must follow PEP8 3) Clean Abstractions. -4) Future Compatibility. Code must not be incompatible with the +4) Future-Compatible. Code must not be incompatible with the long-term vision of either the codebase or of edX. 5) Properly Documented -6) Maintainability/Deployability +6) Maintainable and deployable 7) Robust. All code paths must be manually or automatically verified. @@ -47,14 +47,15 @@ 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) Consistency. Code must follow PEP8 +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 Compatibility. Code must not be incompatible with the +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 - such that it is never run on production servers. +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.) @@ -75,3 +76,10 @@ no hard standards. * 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.