Coding Style¶

Computer programs are not solely about getting stuff to work. They are largely about that, but not solely. It's also important for them to be clear and readable, because no one will want to use your code if they don't feel they can understand and maintain it.

You're encouraged to read my longer essay on coding style

For now, let the following list of rules and guidelines suffice:

All names (functions, variable, modules, etc) should be descriptive and accurate. Honestly, naming things in one of the hardest things in CS: see Two Hard Things. But the fact that it's hard is all the more reason to put thought and care into it.

Be consistent with capitalization and punctuation. Decide on a scheme (say, CamelCase, or names_with_underlines) and stick to it. If there's a standard for your language, use it.

Python prefers snake_case: see PEP 8 Style Guide for Python
JavaScript prefers CamelCase. See Google's JavaScript Style Guide which also covers a lot more than just CamelCase.

Formatting¶

Indentation is important. Code must be properly indented to show the syntactic structure of the program. (With Python, of course, you have no choice.)

A statement that belongs to (is part of) another statement should be indented relative to the containing statement.
Statements that are at the same level in the syntax tree should be indented the same amount.

Remember that screens and printers have finite width. Stick to an 80-character line. Small exceptions are possible, of course, but no one should have to scroll a long way to the right to read your code.

Documentation¶

I usually distinguish between documentation (what the code does and how to use it) versus comments (how the code does what it does). Documentation is for a programmer who wants to use your code (think of JavaDoc from CS 230). Comments are for someone who wants to understand how your code works, maybe because they are going to modify it.

Document the program as a whole. What does it do, and what are its inputs and outputs. Say who wrote it, and when.

Document functions. Each function should be preceded by a brief paragraph explaining what it does, how it works (if necessary) and the meaning of its arguments and return values. Someone should be able to use your function without studying your code.

Document variables and data members. Explain the purpose and use of the data and any non-obvious aspects of its implementation.

Use proper spelling and grammar, except when brevity is more important.

Comments¶

Remember that comments are to help someone understand how your code works. Think not so much of what it does but why it does it.

Don't explain the obvious. The following comments help no one:

// function to process a click
function processClick(event) {
    // prevent the default behavior
    event.preventDefault();
    ....
}

Comment things that are tricky or odd. For example:

    x >> 1     // fast truncating integer division by 2

Normally, you'd divide by two using the division operator, but if you know x is an integer and you are in a context where speed is critical, you might use the fancy shift operator. But don't leave your reader guessing. Explain!

Comments are usually where students worry about how much to do. What is not obvious to a beginner can become obvious to a more experienced coder. But it's also possible to fool yourself: things can seem obvious after you've spend an hour working on some code, but even you yourself, a week later, might struggle to understand the code. (I have personally had experience looking at my own code I wrote a few weeks/months earlier and wondering "what is this gibberish?".) So, err on the side of explaining.

Factoring¶

Functions should do just one thing (suitably defined). Suppose a high-level function calls three low-level functions. What is the "one thing"? Well, perhaps the high-level function is supposed to handle an event of adding something to a task list. It might look like:

function addTaskToTaskList(newTask) {
    addToDatabase(...);
    updateUI(...);
    closeForm(...);
}

The subfunctions also all do "one thing," but a small part of the overall job.

Good coding avoids redundancy and unnecessary duplication of code. This is sometimes known as the Don't Repeat Yourself (DRY) principle. While it can obviously be over-done, avoiding repetition means:

Code only has to be debugged in the one place it's defined, not in all the copies, and
Updates to the one copy of the code propagate to all the places its used.

For example, if you often need to zark some data, defining a function to zark the data and invoking it whenever necessary means that you can debug the zark function once, and if the requirements of the zark operation change, you can update the one function to effect the change. So, we'll add one more rule:

Avoid redundancy and code repetition by looking for suitable opportunities for abstraction via functions, methods, modules and the like.

Rubric

Here's the grading rubric for this assignment:

Gradescope

Be sure to submit to gradescope.

Time and Work

Finally, when you have completed the assignment, make sure you fill out the time and work That report is required.

In addition, you may send me a compliment or criticism of your partner by filling out the Partner Report That report is optional.