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 are introducing a new feature to 61A: 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
- 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.