Code Legibility

When Does Code Need to be Legible?

In this course, you will be coding in programming languages such SQL and Python; the contexts in which you will be writing code includes homeworks, worksheets, 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 such as a compiler or an autograder. Notably, we -- your course staff -- 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 a lower bar than a specific style guide. For example, a specific style guide might require camelCase attribute names (thereby forbidding snake_case names); on the other hand, requiring legible code only means that you consistently follow a single naming convention.

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 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.
• Use of standard SQL types such as VARCHAR, instead of common-but-RDMS-specific types such as TEXT

Similar conventions can be inferred for the other programming languages used in this class. However, if our definition of "legible" is too amorphous, then we recommend (but do not require) the following style guides:

• SQL: https://www.sqlstyle.guide
• Python: https://google.github.io/styleguide/pyguide.html
• Java: https://google.github.io/styleguide/javaguide.html