Use the search bar to discover guidelines and examples.
Questions about the guide? We are always looking to improve our resources, feel free to reach out to Omar with any questions or concerns!
Writing Java code isn't just about writing code that compiles and works. If we wanted code that just got a computer to follow our directions, why not just write it in binary? Truth is, code isn't written for computers; it's written for people.
A computer language is not just a way of getting a computer to perform operations but rather [...] a novel formal medium for expressing ideas about methodology. Thus, programs must be written for people to read, and only incidentally for machines to execute.1
When thinking about what makes code correct, we often think about whether the code is externally correct (does the program output the desired/expected output). However, external correctness is not the only criteria for determining the quality of a program.
Programming in the real world is a highly collaborative activity, so it's very important to be able to write code that is easy to work with and understand. Having clean, readable code also makes finding bugs and errors in your code significantly easier. This code quality guide contains a set of guidelines we expect you to follow when writing code. Writing high-quality programs takes deliberate practice, and this document covers the entire quarter, so these guidelines are not meant to be memorized and understood entirely through one read through. Instead, we'll learn how to write high-quality programs through a process called code review, the practice of reviewing code with an eye towards code quality, using this guide as a reference that you should be able to use to look up rules and examples.
IMPORTANT: This guide covers the entire quarter, so it is not meant to be something that you read through in one sitting -- rather, it is a reference guide that you will hopefully be able to go back to as new topics are addressed. We've tried to make notes of approximately when certain code quality issues become relevant next to section headings. Here is a (linked!) table of suggested readings that you can go through before you turn in each take-home assessment. Note that these suggested readings stack on top of each other -- ie: assessment 4's suggested readings include assessment 3's, which include assessment 2's, etc.
|assessment #||suggested readings|
Harold Abelson, Gerald Jay Sussman, Julie Sussman. 1984. "Preface to the First Edition." Structure and Interpretation of Computer Programs. https://mitpress.mit.edu/sites/default/files/sicp/full-text/book/book-Z-H-7.html#%_chap_Temp_4 ↩