The ease by which other people can read and understand a program (often called "readability" in software engineering) is perhaps the most important quality of a program. Readable programs are used and extended by others, sometimes for decades. For this reason, we often repeat in 61A that programs are written to be read by humans, and only incidentally to be interpreted by computers.
This semester, we will be giving your projects composition feedback. A program is composed well if it is concise, well-named, understandable, and easy to follow. The course readers are members of the course staff in charge of making you more effective programmers. They will review your projects and provide suggestions about how to improve the overall composition of your programs.
Readers will also assign a small composition score (around 3 points) for each project – a few points that may encourage you to improve the readability of your submissions. This score is for the project as a whole, not for individual issues or questions.
Excellent composition does not mean adhering strictly to prescribed style conventions. There are many ways to program well, just as there are many styles of effective communication. However, the following guiding principles universally lead to better composition of programs:
- Names. To a computer, names are arbitrary symbols: "xegyawebpi" and "foo" are just as meaningful as "tally" and "denominator". To humans, comprehensible names aid immensely in comprehending programs. Choose names for your functions and values that indicate their use, purpose, and meaning. See the lecture notes section on choosing names for more suggestions.
- Functions. Functions are our primary mechanism for abstraction, and so each function should ideally have a single job that can be used throughout a program. When given the choice between calling a function or copying and pasting its body, strive to call the function and maintain abstraction in your program. See the lecture notes section on composing functions for more suggestions.
- Purpose. Each line of code in a program should have a purpose. Statements should be removed if they no longer have any effect (perhaps because they were useful for a previous version of the program, but are no longer needed). Large blocks of unused code, even when turned into comments, are confusing to readers. Feel free to keep your old implementations in a separate file for your own use, but don't turn them in as your finished product.
- Brevity. An idea expressed in four lines of code is often clearer than the same idea expressed in forty. You do not need to try to minimize the length of your program, but look for opportunities to reduce the size of your program substantially by reusing functions you have already defined.
This list may grow as we introduce new ideas in the course.
To earn back lost composition points for projects 1, 2, & 3 submit composition corrections for each of those projects by Monday 4/13 @ 11:59pm.
Look at the comments on the submission provided by your grader and make the suggested changes to your code. If you have questions about the comments, the grader's email is included above comments.
Once you make the suggested changes, resubmit the project using OK with the command
python3 ok --submit. If you worked with a partner, only one person has to re-submit. Once you resubmit, the OK website will indicate that a revision has been made. Your revision will be regraded after the deadline.
If you don't have the original folder or code, you can redownload the project and recover your code from OK with the download button found while viewing composition comments.
If the submission does not complete, ensure that you are submitting with ok using the
--submit flag and the email that you are submitting under is the same one that received composition feedback online.