General coding tips

Before you start coding

• Write out pseudocode if you’re creating code with many steps. This might help you break down the many-step process into smaller sub-functions.
• If you’re writing a simple function, note its inputs and outputs (including data types). This might help you with input validation.
• Stop to consider what will work best in the long run.
  • For example, you write one function to clear an old graph and show a new one. It may be better to separate functions to clear old graphs and display a new graph. Consider this if future code may call one function but not the other.
  • For example, you have to show disease counts by province. If your clients seem certain they only want this statistic, you can speed up pages by precomputing this statistic instead of storing all raw data. However, if you might add other statistics (like disease counts over time), it might be better to store all raw data.
  • Stop to consider potential errors in your functions. For example, missing dictionary keys, incorrect input types, or unexpected array lengths.

Make sure your errors are visible

• Use assert statements and error messages to make sure variables contain the data you expect.
• Never handle exceptions with code that prevents error messages or at least log messages. For more information, read The Most Diabolical Python Antipattern (realpython.com).
• Use Dev Tools to check the data your code is using while executing. It’s very common to find out that you have unexpected data types or you forgot to delete old variables.

Reuse code as much as possible

This makes sure you only have to fix bugs in one place instead of in several copies of the same code.

• Avoid copying code within a file. Could you create one function called in two places?
• Avoid copying code from one file to another. Could you export that code between files as a function?
• Avoid copying a module/library into many folders across multiple projects. Could you just link to one source directory for that library?
• Especially with d3.js, you might notice a lot of repetitive code to set attributes. Could you create reusable functions to set attributes? For example, an opacity function that sets the opacity to 0 if the data is invalid or 1 otherwise.

Avoid inconsistent results

For example:

• If you have a dropdown to select a date and a slider to select a date, make sure they both update whenever the user interacts with either one. Otherwise, users will be confused.
• If you delete a graph’s DOM elements in a function, clear any variables related to that old graph on the very next line. Don’t put these two steps in different functions. Then, future programmers will remember the two steps must go together.
  • Clearing variables means you delete them or set them to null values. it prevents your code from accidentally using the old graph data without creating errors.
  • How to delete variables - Stack Overflow
  • How to set variables to null values - Stack Overflow

Avoid global variables when possible

They make code hard to update since you might break many parts of a file by changing just one variable.

Potential alternatives are to have a single state object with the variables as properties. Also, you could turn the global variables into class attributes.

When you should use a class

You should use a class when:

• your code creates something you could have multiple of. For example, multiple graphs, tables, forms, etc.
• you have many functions which access the same global variables. These could be turned into multiple methods which access the same attributes.
• you find yourself fixing bugs due to global state variables being overwritten. This might be fixed by creating protected attributes and input validation in setter methods.

Fork your projects and merge changes

• If you’re using Git and aren’t sure how to do this, here’s a Git and GitHub tutorial - Youtube.
• If you’re using an integrated development environment that doesn’t support this (like AWS Cloud9), try creating two folders: a stable folder to show clients bug-free code and an unstable folder to work on new features. When you’ve tested the new features to make sure they’re bug-free, move the code from the unstable folder to the stable folder.