Code Legibility

When Does Code Need to be Legible?

In this course, you will be coding in programming languages such SQL and Java; the contexts in which you will be coding will include homeworks, exams, and even the discussion board. All of this code must be legible, which we define as "is a skilled user able to understand the logic just by reading it?".

All of your code is reviewed by a human being, such as your professor or TA. Please write your code for them, not for a machine like a compiler or an autograder. Notably, we must be able to understand your code without the assistance of automatic formatters ("linters"), compilers, or output from unittests.

What Does "Legible" Mean?

We do not grade on compliance with a specific style guide. Instead, we only ask that the code you write can be understood by a skilled human; in other words, that it's "legible".

Legibility is usually a lower bar than a specific style guide. For example, in SQL "legibility" typically means:

SQL-reserved keywords are in all-caps (eg, SELECT, AND, AVG, etc, instead of SeLeCt, and, Avg, etc)
Relation names are in title-case (eg, Movies, instead of MOVIES or movies)
Attribute names are in lower case (eg, releaseDate or release_date, instead of RELEASEDATE or RELEASE_DATE)
If on a new line, multiple AND/OR statements are indented
If on a new line, subqueries are indented
Newlines added wherever they aid comprehensibility, and definitely when the query exceeds 80 columns in width
Use of standard SQL syntax, such as -- for comments (instead of // or /* */), ' for strings (instead of "), = for equality (instead of ==), etc.

However, if our definition of "legible" is too amorphous, then we recommend (but do not require) the following style guides:

Report abuse