Making Good CodeAKA: So, You Wrote Some Code. Now What?

Ray HaggertyJuly 23, 2015

Step 1: Debugging

What is Debugging?

• The term “debugging” was popularized in the 1940s by Admiral Grace Hopper• Debugging is, essentially,

the fixing of errors in your code

The Three Major Types of BugsCompilation Errors• These prevent your code from executing at all• Examples: mismatched delimiters, not ending loops

Run-time Errors• These occur when your code attempts an impossible operation• Examples: dividing by zero, calling a function that doesn’t exist

Logic Errors• These will not throw an error, but give unexpected results• Example: using ‘and’ & ‘or’ incorrectly, off by one

Quick & Dirty: Using Print Statements

Quick & Dirty: Using Print Statements

Expectation Reality

Interpreting Error Messages

• References script or function error was generated in• Gives the line at which the error

was detected• This does not necessarily mean

the line the error is on

• Short explanation of what the computer attempted and couldn’t accomplish

Absolutely Correct: Using a Debugger• Debuggers act like version control for your programs, saving the state

of every variable at every instruction

• When the program breaks, you may execute instructions on the last state of the program

• Also allows backtracing to find the faulty piece of code directly

Absolutely Correct: Using a Debugger• Debuggers require a debug-mode compile and are slow and memory

intensive

• Check your code in release mode after running it through the debugger.

• Sample debuggers:• Python includes the extensible Pdb debugger• MATLAB has sldebug, the simulink debugger• R can use the Dr. Mingw “just-in-time” debugger

Step 2: Testing

What is Testing?

• Just because your code worked on one specific problem, that DOES NOT mean it will necessarily work on other, similar problems

• Just because you didn’t see an error message, that DOES NOT mean, it is running correctly

• Testing is a way to ensure that your code will behave appropriately under the circumstances it promises to

• Need to make sure that your output is actually scientifically correct

The Four Major Testing CasesBase Case• This is expected input

Edge Case• This is a minimum or maximum acceptable parameter

Corner Case• This is the intersection of multiple Edge Cases

Boundary Case• This is near the Edge Case, on either side

Quick & Dirty: Test Various Inputs

• Manually test your code by testing each of the types of testing cases and comparing the results to what you expect

• For example if the function expects the input to be between 0 and 100, we might test the following inputs:• 22, 50, 89 (Base Cases)• 0, 100 (Edge Cases)• -1, 1, 99, 101 (Boundary Cases)

Absolutely Correct: Unit Testing

• Unit tests are pieces of test code that exist simply for the purpose of testing your code

• Since they exist outside of the code, they are durable. The same unit test can check multiple versions of your code

• However, you need to be very careful writing them

• Good idea: write a unit test every time you fix a bug

Exception Handling

• When your code encounters an error, you want it to alert the user to the problem and exit as gracefully as possible

• Exception Handling changes the flow of a program to handle abnormal or unexpected conditions

• For example, if a FASTA file contains an unexpected symbol- tell where it is and be informative

Exception Handling

• Try/Catch Statements• allows you to override the default error behavior

Exception Handling

• Asserts• Allows you to throw custom errors if condition is not met

Step 3: Using Best Practices

Why Should You Use Best Practices?

• In all likelihood, you will not be the only person using or looking at your code

• In all likelihood, you will want to make revisions to your own code at some point

• In all likelihood, you will want to have fast code

Encapsulation

• Encapsulation is breaking your code down into smaller parts and assembling them like legos

• This is actually a somewhat complex topic, but in the simplest sense, it is breaking out sections of your code into new subfunctions, and calling those within your main script or function

• Encapsulation has several advantages:• Code readability• Better for testing• Future-proofing• Code reuse• Controls variable scope issues

Code Testing

• Since encapsulation breaks your code down into individual functions, it makes unit testing very straightforward

• Ensuring that each subfunction works appropriately is critical for the other benefits of encapsulation

Future-Proofing

• Since your code is encapsulated into small, independent blocks, it is very easy to reuse and replace each subfunction

• If you decide you want to change the way part of your code works, you can easily replace it without worrying about the entire script breaking

Code Reuse

• Conversely, you may find yourself needing to write a lot of different scripts that perform the same function(s)

• You could just copy/paste, but that is sloppy and could introduce errors

• If you’ve already used encapsulation, then you can easily reuse a subfunction in a new script

Variable Scope

• The scope of a variable refers to which parts of the code can “see” and access that variable

• Generally, you want your variables to be of a smallest scope possible, so they are protected

• There are lots of different scopes, but the two main ones are:• Local

• Only visible to a small section of the code (e.g. a subfunction)• Non-local

• Visible to a larger section or all of the code

Header Comments

• A header comment is a block comment at the top of your code to help readers of your code

• It should include:• Explanation of what the code does (Input/Output)• Name and contact info• Date edited• Requirements (packages, software versions)

Header Comment Examples

Header Comment Examples