WEB 150 - Winter 2015

Final Assignment: Code Review - Due Mar. 24

For your class final, I want you to annotate a piece of code that you didn't write. Code reading is a crucial part of being a well-rounded developer: it's the way that you learn about browser features, steal acquire new techniques, and become better at working with teammates or old code.

At this point, you should have sent an e-mail with a few options that you'd like to review. From those options, choose one, bearing in mind the following points:

• You do not have to comment on the entire file, but the part that you annotate should be at least 50 lines of code.
• Try not to pick a section that's already been commented. A few comments are fine, here and there, but I'm not interested in your ability to translate annotations that already exist.
• If choosing an excerpt, try to pick a piece of the file that you personally feel is intellectually challenging. Don't show me code that performs a simple and uninteresting task, e.g., just adds a class or sets a style.

Copy the code that you're commenting on to a new file, and add the following information in a block comment at the head:

• Give me a URL for the original code (and, if this is only a part of the file, tell me the original line numbers you took it from). I want to be able to read what this looked like in context.
• Write a short paragraph that puts the code in context: What does it do in a general sense? How does this code fit into the wider program, if there is one? When would this be called, and what other libraries (jQuery, Underscore, etc.) does it depend on? What do you find interesting about it?

Now, within the code, add line/block comments to explain the code. I should be able to read your documentation and feel like I understand what it does, and why it does it. I don't expect you to comment on every single line. But I do want you to translate the code into a readable, literate form. The following guidelines may be helpful.

• Make sure to call out/comment on lines that fit the following categories:
  • Code you don't understand
  • Code that seems tricky or confusing
  • Code that is buggy or has mistakes
  • Function calls that are unfamiliar to you and aren't self-explanatory (i.e., not document.getElementById() or the like)
• Use JSDoc standards to annotate function arguments and return values, so I can see what goes in and out of any functions declared in the document.
• Give examples of likely values for variables. For example, if a function takes an event argument, tell me what kind of event it is likely to be, and property values that might be included on that event.
• If there are other comments already in the file, be sure to initial your own comments to distinguish them. Feel free to comment on the other comments, if those do not seem adequate to you (add examples, add context, or clear up misunderstandings)

When the file is complete, post it as a GitHub Gist and e-mail me with the URL for that Gist. You may also post it early on, and then revise as you continue working on the assignment. I've provided a sample code report here for reference.

This assignment is a broad experiment that (as far as I'm aware) has not been tried at SCC. If you have any questions, please feel free to contact me for more information. At the same time, I have the expectation that you will be professional and thoughtful with this: we are all adults, and you're being given ample time to assemble this report. When in doubt, put yourself in the shoes of someone who has given you this code as an interview question, and aim to make a good impression on them.