Notes on Programming Assignments

Notes on style

  1. I expect your code to be reasonably commented (not overly so) and well-structured. A comment explaining each function can be a good idea. Clean code should be readable on its own but you should guide the reader. A comment explaining each function is a good idea. Additional comments that point out anything that's non-obvious or a special case are also helpful.
  2. Do not put all functionality in one function. Break your code down into sensible functional blocks. Make your code readable: hide details in functions.

  3. Pick sensible variable names. For example, a stream of variables named a1, a2, a3 is a sign that you're doing something wrong. Names don't have to be long to be meaningful and i and j are perfectly fine names for index variables. I strongly encourage you not to use Hungarian notation (prefixes or suffixes indicating variable types, as popularized by Microsoft); there is no compelling need to embed data type codes into your variables. Just strive to write the most readable code you can. Don't let needless comments or obscure variable names get in the way of reading the logic of the code.

    Long names are more sensible for varaibles with a global or wide-area scope. With longer names, think about which is more readable: longNamesWithStudlyCaps or long_names_with_underscores.

  4. Make sure your indentations are reasonable. I will not accept code that looks like: 

    if (whatever)
    {
        statement;
        statement;
    }
    Use either: 
    if (whatever) {
        statement;
        statement;
}
    or 
    if (whatever)
{
        statement;
        statement;
}

  5. DO NOT MIX LEADING TABS AND SPACES!! IF YOUR EDITOR DOES SO, FIX THE FILE BEFORE SUBMITTING IT.

    The reason this is important is because my tab stops may be set differently than yours, so the spaces you or your editor uses to pad things out or create a half-tab may accomplish totally diferent results for me. Your code will appear inconsistenly indented to me and I won't properly see the structure of your code.

    Your tab settings are probably not the same as mine. If you mix leading spaces and tabs, then the indentations will look wrong to me and you will lose points. To check, look at your program filtered with the expand command, changing the tab stop setting. For example, 

    expand -t 3 <Server.java

    and 

    expand -t 11 <Server.java

    should both appear properly indented and readable. If this is not the case, fix your tabs or convert them to spaces (you can use the expand command for this).

    With vi, just use tabs and set whatever tabstop you want to see: 

    set tabstop=4

    You can ensure that tabs are converted to spaces by setting: 

    set expandtab
set softtabstop=4

    Setting softtabstop makes the backspace key treat the four spaces (in this example) like a tab.

    If you are using emacs, run:

    (setq-default indent-tabs-mode nil)

    in your .emacs file so emacs won't use tabs for any new indentation. To replace all tabs with spaces in the current buffer you can use C-x h M-x untabify.

    I am posting the emacs notes for guidance. I do not use the emacs editor. Learn how your editor behaves and how to make it behave the way you want to.

  6. Check for errors - bad commands, missing arguments, extra arguments, lost connections. Your code should be robust and not die when bad things happen that you can anticipate. If you use Java, catch sensible exceptions and print human-friendly messages.
  7. You may use things like socket routines from the sample programs if it makes sense to do so but a lot of my other code other code may be of little use. Do not leave stray variables or useless functions in your code. Attribute your sources; do not copy code from other sources.

Losing points on submission

Beyond logic errors, you will lose points for:

  • Unnecessary files submitted.
  • Mixing leading tab and space characters in your code.
  • Sloppy coding - commented-out code.
  • Sloppy coding - strange indentations.
  • Sloppy coding - pathetic style, lots of blank lines, ...
  • Poor error checking.
  • No comments.