Code Style

This class focuses on the study of algorithms and data structures, exploring both their theoretical foundations and practical implementations. Equally as important, however, is the art of producing clean, understandable, and correct code.

The essence of high-quality code lies mostly in its clarity and readability. Readable and clear code is easier to debug (and less prone to bugs in the first place) and it is easier to work on in a team (and you're likely to work on assignments in pairs much more often than on your own).

With this in mind, we will share with you four broad, easily memorable principles that you should follow when you are writing code.

You should apply these principles on every assignment. Do so while you develop; writing messy code then modifying it to adhere do the principles defeats the purpose of this (and is more work). You will be graded on style and lose points by breaking them (more on this at the end of the page).

Here are the four principles:

P1 Descriptive Naming

Descriptive naming involves choosing names for variables, methods, classes, and other entities that clearly reflect their purpose, usage, and scope. Good names make code more readable and understandable without requiring additional comments to explain the purpose of a variable or block of code. While developing your solution, consider the following::

• Variables: Choose names that describe the data variables hold. Examples:
  • Good: nounToIdMap, newCapacity, numberOfElements (easy to guess their purpose with no further context).
  • Bad: temp, data, p (either vague or not useful).
• Methods: Name them based on the action they perform or the result they return. Examples:
  • Good: resizeArray(), updateBestWeight(), validateNamesList().
  • Bad: validate(), handleData().
• Suggestions:
  • Don't be afraid of using long names; in fact, you're encouraged to! While it might seem cumbersome to rewrite the same long names repeatedly, IntelliJ does most of the work for with its tooltip and autocomplete features once you start typing.
  • Adopt a consistent naming convention (e.g., here is the Java codebase's) and stick to it.
• Common mistakes:
  • Giving two entities very similar names, e.g. n and N, or list and lists.
  • Using ambiguous abbreviations (e.g usrPrf instead of userProfile).

P2 Modularity and Reusability

Modularity refers to the practice of structuring a program into distinct, independent modules that can be combined together to form a complete system. Reusability is a related concept where modules are designed to be reused in different parts of a program or in entirely separate ones. Consider the following when writing your programs:

• Helper methods: Utilize private helper methods to encapsulate specific, reusable logic that is constantly used throughout a class. Two examples from Percolation: methods like convertCoordsToIndex(int row, int col) for converting grid coordinates to an array index and validateCoordinates(int row, int col) for checking boundaries.
• Constants: Employ well-named constants for recurring values to eliminate ambiguous magic values (integers, strings, etc). Examples:
  • Good: Utilizing a constant like CONFIDENCE_INTERVAL in PercolationStats to compute confidence intervals.
  • Bad: Repeatedly using 1.96.
• Suggestions:
  • Utilize helper methods to validate function parameters if said parameters are repeated in multiple methods.
  • Thoroughly inspect the assignment specifications to see which parts of the code can be modularized.

P3 Effective Comments

Effective comments provide clarity and context to code, explaining why certain decisions were made, the purpose of complex sections, and how they fit into the big picture. Writing good comments is not an easy skill to master, and it is very easy to either write too many or not enough.

• Writing too many comments: Don't use comments to describe what the code does; use them to provide context instead. Writing numberOfElements++; // Increments number of elements is completely useless since it is obvious from the code that it incrementing a variable.
• Writing too few comments: If you see a long stretch of code without a single comment, you'll probably get lost trying to understand what it does. This is where effective comments tie in with modularity (P2), since often a long stretch of code can be broken up into a few blocks of code, each serving a particular purpose.
• Method comments: Use these to describe parameters and return values, as well as a high-level overview of the method's logic.
  • Good: // Takes char target and String text as parameters. Finds and returns the first index at which target appears in text
  • Bad: // Iterates through the second parameter using a for loop to find where the target appears
• Variable comments: Write variable comments that describe the information it stores as well as any relevant relationships with other data.
  • Good: // number of elements in the hash table
  • Bad: // num elems
• Local comments: Local comments should describe the purpose of the block of code it refers to.
  • Good: // Counts and stores number of replacements in inputText in textCounter
  • Bad: // While loop

In summary: comments should act as documentation that provides context, rather than a verbatim step-by-step description of its logic. The latter should be self-explanatory to a large extent (if you follow the good naming practices explained in P1).

P4 Simple Programming

Simple programming is about keeping the code as straightforward as possible and avoiding unnecessary complexity.

One common source of overly complicated code is programming before thinking. Before typing a single letter on your laptop, you should stop and think clearly about what you intend it to do. Most of us tend to start writing code with only a fuzzy idea of the precise end goal.

By developing this way, we often realize that the code from 5 lines ago isn't quite right; so we backtrack 5 lines, update it and go back to where we were. But now the fix isn't compatible with another block, part of written with the previous version in mind. Soon enough, the implementation changes from a sequence of clearly connected lines to a series of messy ad-hoc patches that are hard to understand. This is especially relevant in the implementation of algorithms and data structures, since these programs are often logically dense (i.e. a few lines of code have lots of non-trivial conceptual ideas).

Note that these are principles, not hard-and-fast rules. They help you write better code, not to constrain your ideas. You might find it important to need to violate a principle them occasionally, and that's okay (if justified).

Grading

Adhering to these principles as you compose your assignments is crucial. Rewriting messy code later defeats the purpose of learning style conventions, and is much more work than adhering to them from the start. Furthermore, all but your first assignment submission will be graded on style of based on these 4 principles. Your code feedback may include style warnings and style errors:

• A style warning doesn't incur a point deduction, points out the violation of one of the principles. It is applied to violations that only appear once and don't affect the overall code greatly.
• A style error incurs a 1-point deduction. It is applied for repeated break violations of the same principle, or a single serious deviation.

A note on Checkstyle

You have probably noticed the Checkstyle feedback supplied both by IntelliJ (the yellow warnings) the autograder output in TigerFile. Since you will be graded on style principle rather than Checkstyle violations, are they safe to ignore? No. For context, Checkstyle checks a long list of rules that the Java source code adheres to (available here). They are helpful rules, but are insufficient to enforce good code style.. Moreover, some Checkstyle checks are customized to a particular assignment; pay careful attention to these, as they often flag serious issues (such as using a prohibited library or using a loop in a method that is supposed to take constant time).

We will not deduct points based on the number of Checkstyle warnings or errors, but use the process specified above instead. But Checkstyle is your friend: odds are that a program with several Checkstyle violations is doing something wrong, and will incur a style (or correctness) error somewhere. We strongly advise reading and payin g attention to its feedback, disregarding it only if you are confident that the warning is a false positive (i.e., your code does not violate any style principles with good reason).