In this interlude, we will discuss code styling and formatting in order to make our code easier to read and write.

Tracing our thought patterns with comments

One important thing to do using code is to document our thought process and explain how our code works. Even if this is code which you may never have to show anybody, think of it as a way to help you think clearer, as well as treating your future self. After all, you may understand your code right now, but in six months... you'll probably have zero clue about what it's doing.

In Python, the basic comment pattern is to put a # before any code. Like this:

a = "hello" # this is a comment!
# this is another comment which spans a whole line.

It even shows up in gray! Visual Studio Code should also display comments in a different colour.

Comments are one of the most flexible tools in our repertoire to explain what's going on. They're usually used in two ways, and to demonstrate, I've found my own code to show how I've been using comments personally. Of course, the code may be a little complex for you, but the idea is that you'll have a basic understanding of what's going on (provided you can read English).

def recursed_min(start, end, increment):
  # calculate number of increments needed beforehand
  recursions = ((end - start) / increment) + 1

  # fill values with 65535 - arbritrary large value, no significant meaning
  values = np.full((int(recursions), 2), np.inf)

  for index, min_point in enumerate(np.arange(start, end, increment)):
    # minPoint is the intended minimum point i.e. half the period
    # given the natural period of the sin graph is 2π:
    period = np.pi / min_point

    # translate the equation
    predicted = amplitude * np.cos(period * XVALS) + mid

    # calculate Least Squares Sum
    ls_sum = utils.sumOfDifferenceSquares(DATA_FLAT, predicted)
    values[index] = [ls_sum, period]

  # get index of lowest value in array
  lsqs = values[:, 0]  # least squares
  min_estimate = np.where(lsqs == np.amin(lsqs))[0]

  if increment == min_increment:
    return values[min_estimate][0][1]
  else:
    # convert back to day
    minimumDay = start + min_estimate * increment

    print("Min at", min_day, "for increment", increment)
    return recursed_min(
        start     = min_day - (threshold * increment),
        end       = min_day + (threshold * increment),
        increment = increment / 10
    )

A lot of that code may go above your head, and admittedly, the stuff I wrote a year ago makes little sense to me right now. What is the ls_sum variable? What does ((end - start) / increment) + 1 do? What does v represent in my loop?

However, you might be able to notice that my comments document my thought process and explain exactly what I'm doing in this code. I might have forgotten the intricate details of my code, but my comments explain what the variables mean. It explains certain choices - why did I fill the values list with the number 65535? Because it's an "arbritrarily large value, no significant meaning".

These are the choices which you should be documenting with comments. Explaining what your code does in English, so that anybody can follow along - even if they're not well versed in what your code does, or how it does it.