Skip to content

Latest commit

 

History

History
159 lines (117 loc) · 9.91 KB

coding-best-practices-workshop.md

File metadata and controls

159 lines (117 loc) · 9.91 KB

#Week 5 - Mar 17: Workshop 2 #Creative Coding Best Practices

##Time management

###Activity: time estimation

  1. List out the technical tasks / todos you need to accomplish this week.
  2. Break into subtasks and estimate time for each. How long do you think each subtask will take you? Be as honest as you can.
  3. Time the subtasks as you complete them throughout the week.
  4. Bring notes on your estimated and actual times to class to discuss.

##Version control

  • DIY -- copy the folder and rename with date. Save copies on different machines or clouds just in case!
  • Github -- tutorial here

##Code organization

  • Name well -- Make sure variable names reflect what they describe on screen, class/object names reflect what they are, and function names reflect what they do.
  • Comment -- Describe what's going on in English your parents can understand. Go line-by-line in your code if you have to. The more self-explanatory your variable/function names, the simpler your comments can be. It may seem obvious to you at the moment, but if you come back to your code hours, days, weeks, years later, you will thank yourself!
  • DRY -- Don’t Repeat Yourself. Make variables for number values or functions for blocks of repeated code so you can make a change without having to update 5 different spots.
  • Modularize -- Organize your code into functions so your code is easier to read and you can turn functionality on/off more easily. When your project starts to get larger, split your code into multiple files instead of having one really long file.
  • Format -- Format your code early and often, line up if blocks, for loops, and functions. This will help you (and anyone you ask for help) to see and understand what’s going on. (Cmd/ctrl+t in Processing will do it automatically for you!)

##Common errors

"There are two hard things in computer science: cache invalidation, naming things, and off-by-one errors."

  • https://www.iiitd.edu.in/~jalote/papers/CommonBugs.pdf
  • Human errors -- It is always good to sanity check that you are actually running the code you expect to be running
    • Are you really running the correct file or program?
    • Did you save the program before running it again?
    • Did you upload the latest version of your code before testing?
    • Is your change actually supposed to be happening right now? (i.e. if you made a change to see purple during the evening hours, but it's still daytime, you won't see purple until later)
    • Copy/paste errors -- If you copy and paste, make sure you are careful
  • Compilation errors -- Errors that stop your program from compiling. In Processing, openFrameworks, etc when you try to run the code will not compile and start. In JavaScript, the code will likely run until it hits the incorrect line in your code. Most compiler errors are caused by mistakes that you make when typing code. For example, you might misspell a keyword, leave out some necessary punctuation, or try to use an End If statement without first using an If statement.
    • Unmatched braces / scope
    • Misspellings
    • Variable not properly defined
    • Variable not defined in the correct scope
    • Undeclared function
  • Runtime errors -- Errors that occur while your program runs. These typically occur when your program attempts an operation that is impossible to carry out. Technically, all JS errors are runtime errors.
    • Division by zero
    • Infinite for loop.
  • Logic errors -- Errors that prevent your program from doing what you intended it to do. Your code may compile and run without error, but the result of an operation may produce a result that you did not expect.
    • Confusing = and ==
    • Off by one error
    • Array out of bounds error
    • Arithmetic errors
    • Scope issues, referencing wrong variables

Part 2: Each person picks one error. Create a diagram / illustration of the error. Could be more conceptual… should not be code example. Show diagram to class, explain what the error is, how to detect it, etc. (~20 mins)

##Debugging strategies

Parts adapted from Clay Shirky’s A Brief Introduction to Debugging.

###Prepare

  • Don’t panic. (Do take a deep breath.)
  • Take a snapshot. Don’t go backwards! Keep track of everything you try.
  • Write a message asking for help.

###Observe

  • Is everything plugged in?
  • What just changed?
  • Read the code like a computer.
  • What do the error messages say? Read the error messages. Don’t be worried if you don’t know what they mean, google can help you!
  • LMGTFY
  • Print -- Print out any and all values that might help you better understand what's going on. Label what you're printing using String concatenation.

###Change

  • Can you work from one end to the other?

  • Write your own error reporting
  • Process of Elimination
    • Comment out -- Temporarily comment chunks of code in and out to track down the problem area.
    • Simplify -- Get rid of all code except for the bare minimum required to demonstrate what's going wrong.
  • Sanity check: are you looking at the same thing you are changing?

###Defend

  • Premature Optimization Is The Root of All Evil
  • Only do one thing at a time.

  • Save working versions! On different hard drives / machines!
  • Write tests / examples to ensure it keeps working, doesn't break when you're not looking.
  • Take breaks -- sleeping on it or letting things process in your subconscious can help you arrive at an answer.

###Be social

  • Ask for help -- Don’t waste hours or days stuck on a problem. If you have tried all the above yourself and looked around online, ask for help. Places to ask include forums, IRC, mailing lists, classmates. See below for tips for asking for help.
  • Talk it out -- Find a friend and talk through your problem. They don’t necessarily need to completely understand your code. Sometimes just walking step by step through a problem can make you see a detail or solution you were overlooking.

##Asking for help

##Activity: debug competition

Part 1: Break into teams of 2 (make sure each group has one person that knows Processing or code well). Create a Processing sketch, and take a screenshot of the output. Then change only one line / insert one bug of the sketch code to “break” it. Broken could mean it won’t run or it looks wrong, compared to the screenshot you took.

Part 2: Each team of 2 will be given a different team’s sketch and desired output screenshot, and try to debug/unbreak it as fast as possible (get it to run and match the output of the screenshot). Repeat once more with another team’s sketch.

Part 3: We add up the times to debug each sketch, “winning team” is the team whose sketch took the longest / was the hardest to debug. Debrief and discuss.

  • What types of errors did we see?
  • Which were hardest to find?
  • Which were easiest?
  • What makes a program hard to debug?
  • What strategies did you use?
  • How did we think about writing a sketch to be hard to debug / hide an error?
  • What realizations did you have while creating or debugging?

##More resources

##Tools