Skip to content

E
edx-platform
Commit 0f8d2021 by Piotr Mitros Committed by Matthew Mongeau
Options

Documentation Standards

parent 74b5b11f
Showing with 15 additions and 7 deletions
doc/code_standards.txt
...@@ -30,12 +30,12 @@ following standards: ...@@ -30,12 +30,12 @@ following standards:
1) Test Suite. Code must have reasonable, although not complete, test 1) Test Suite. Code must have reasonable, although not complete, test
coverage. coverage.
2) Consistency. Code must follow PEP8 2) Consistent. Code must follow PEP8
3) Clean Abstractions. 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. long-term vision of either the codebase or of edX.
5) Properly Documented 5) Properly Documented
6) Maintainability/Deployability 6) Maintainable and deployable
7) Robust. 7) Robust.
All code paths must be manually or automatically verified. All code paths must be manually or automatically verified.
...@@ -47,14 +47,15 @@ following standards: ...@@ -47,14 +47,15 @@ following standards:
1) Testable. We do not require test coverage, but we do require the 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. 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 3) Clean abstractions or obvious throw-away code. One of the goals
of scaffolding is to define proper abstractions. 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. long-term vision of either the codebase or of edX.
5) Somewhat documented 5) Somewhat documented
6) Unpluggable. There should be a setting to disable scaffolding code 6) Unpluggable. There should be a setting to disable scaffolding code.
such that it is never run on production servers. By default, and by policy, it should never be enabled on production
servers.
7) Purpose. The scaffolding must provide a clean reason for existence 7) Purpose. The scaffolding must provide a clean reason for existence
(e.g. define a specific interface, etc.) (e.g. define a specific interface, etc.)
...@@ -75,3 +76,10 @@ no hard standards. ...@@ -75,3 +76,10 @@ no hard standards.
* Each contributor is responsible for finding a person to review their * Each contributor is responsible for finding a person to review their
code. If it is not clear to the contributor who is appropriate, each code. If it is not clear to the contributor who is appropriate, each
project has an owner 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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment