in the summer, after both papers are done, before we "go crazy" we should document the project:
-
Every subdirectory should include a very small README, even simpler than CSE 8B ones. These READMEs should document intent and purpose and motivation. They should NOT document what each individual file does.
-
Every python file should have a file header that documents, again, the motivation behind the file. No implementation information.
*Every class header should document what the purpose of the class is, using pydoc format. This is where we can start talking about implementation, but at a high level.
- Every function header should explain what implementation/motivation underneath the logic.
Why this way? Because we assume the programmer can already read Python. So every header above should be 1-2 sentences, really concise and simple. In a single sentence, these headers and comments are meant for people e.g. who read the paper and are now trying to see how our Python translates into the higher level logic implementations and design decisions.
in the summer, after both papers are done, before we "go crazy" we should document the project:
Every subdirectory should include a very small README, even simpler than CSE 8B ones. These READMEs should document intent and purpose and motivation. They should NOT document what each individual file does.
Every python file should have a file header that documents, again, the motivation behind the file. No implementation information.
*Every class header should document what the purpose of the class is, using pydoc format. This is where we can start talking about implementation, but at a high level.
Why this way? Because we assume the programmer can already read Python. So every header above should be 1-2 sentences, really concise and simple. In a single sentence, these headers and comments are meant for people e.g. who read the paper and are now trying to see how our Python translates into the higher level logic implementations and design decisions.