\( \newcommand{\vecIII}[3]{\left[\begin{array}{c} #1\\#2\\#3 \end{array}\right]} \newcommand{\vecIV}[4]{\left[\begin{array}{c} #1\\#2\\#3\\#4 \end{array}\right]} \newcommand{\Choose}[2]{ { { #1 }\choose{ #2 } } } \newcommand{\vecII}[2]{\left[\begin{array}{c} #1\\#2 \end{array}\right]} \newcommand{\vecIII}[3]{\left[\begin{array}{c} #1\\#2\\#3 \end{array}\right]} \newcommand{\vecIV}[4]{\left[\begin{array}{c} #1\\#2\\#3\\#4 \end{array}\right]} \newcommand{\matIIxII}[4]{\left[ \begin{array}{cc} #1 & #2 \\ #3 & #4 \end{array}\right]} \newcommand{\matIIIxIII}[9]{\left[ \begin{array}{ccc} #1 & #2 & #3 \\ #4 & #5 & #6 \\ #7 & #8 & #9 \end{array}\right]} \)

Honor Code

Please remember the collaboration policy for this course. You can discuss homework problems with other students and exchange general ideas about how to solve them, but you should write your own code and write up your own solution to math problems. You should not share code with other students or copy another student's code.

Grading

Satisfactory performance on an assignment will earn a B. For programming problems, this means your program loads into the browser and runs with no errors (check the JavaScript Console) and does the bare minimum. A "conspicuously excellent" program will earn an A, which means that it runs without errors, follows all the detailed instructions of the assignment, is well documented, and is excellent in some way. This may involve some measure of creativity or extension to the basic assignment.

Documentation

You should document what isn't obvious from the code. That usually means saying not what something does, but why it's there and how it fits into the overall program. Line by line documentation is not necessary, but certainly every function needs some explanation.

Try to put yourself in my shoes, or the shoes of someone reading your code who doesn't know what the program is supposed to do or how it's supposed to work.

For identification purposes, every program must have the author(s) names and the assignment name or number at the top.

Note that I have deliberately not always demonstrated good documentation in the example programs because we will study them to determine what they do and how they work. You are encouraged to document your own copy as a way to help your understanding.

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 Scott's longer essay on coding style. JavaScript coding style is not that different from Java or Python style, and there is room for alternative styles.

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

  1. Don't explain the obvious. What counts as obvious depends on your audience, but don't think about me as your audience, but rather another student in our class. They understand the basics of the language and the course, just as you do, but they may not understand your thinking about the program and the way you went about coding it.
  2. All names (functions, methods, variables, modules, etc) should be descriptive and accurate. You'd be surprised at how often I have read code where the name may have been descriptive when the code was first written, but subsequent editing has rendered the name obsolete and misleading.
  3. 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. Here is Google's JavaScript Style Guide that might be good to skim. Generally, their Naming Rule is to use camelCase with a lowercase initial, except for classes. You should consider doing the same.
  4. Functions should do just one thing (suitably defined). A function that adds a tree to the scene is good. A function that adds two trees to the scene is bad (what if the user wants three trees?). A function that adds all the trees to the scene is also good, even if the number of trees in the scene is two.
  5. Indentation is important. Code must be properly indented to show the syntactic structure of the program. Use an editor that will help you with this, such as Visual Studio Code, Atom or Emacs. I like four spaces of indentation; Google prefers two spaces. As long as you are consistent, either is okay.
  6. 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.
  7. Document the program as a whole. What does it do, and what are its inputs and outputs. Say who wrote it, and when. This is typically written as a block comment at the top of the file.
  8. 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.
  9. Document variables and data members. Explain the purpose and use of the data and any non-obvious aspects of its implementation.
  10. Document any code that is not obvious.
  11. Use proper spelling and grammar, except when brevity is more important.
  12. Remember that screens and printers have finite width. Stick to an 80-character line.

Furthermore, 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 overdone, 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 it's 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:

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

Turnin

To ensure consistency, I use Gradescope, so be sure to upload a Gradescope item when you (and your partner) are done. If you worked with a partner, include them in the group, so I only have to grade the work once and it counts for both.

There are two kinds of problems on assignments: programming problems and "math" problems. Programming problems will be turned in by putting the code in the correct file in your account on the CS file server. I will view it there. Do not change the code files after the deadline.

For non-programming problems, answers can be typed up and emailed to me. If a sketch is required, try to use a drawing program if possible and attach a GIF or PNG file to your email or embed it in the document. I may also share a Google doc with the questions — in this case, you can make your own copy of the Google doc, enter your answers into the document, and submit by sharing your copy with me (be sure that an email message is sent to me in this case). If necessary, you can write out your solutions by hand and make an electronic picture (e.g. with your cell phone), but please be neat and use a dark pencil or a pen.

Deadlines and Lateness

Please see the late assignment policy described in the course syllabus for the policy that will be used this term.