Constants and Comments

Types of Comments

Do you remember the script count_to_ten from the last page? The next script, count_to_ten_documented, is different in several ways. 

First, it has a block comment at the top.  Technically this block comment is called a docstring. Docstrings start with a triple quote """ and end with a triple quote """. People often use these to create block comments and you can write as many lines of notes in between a pair of triple quotes as you want. Use caution when placing docstrings in your code as they could become the documentation that is associated with a function or method.

Also, each line of code has a line comment starting with # to its right, explaining what the code does. Line comments can also be placed above a section of code if they are very long, to avoid having to scroll sideways to read it.

In Python, constants don’t exist at the level of coding we are currently describing, however, we can still use styling to indicate to other people that may read our code that we are intending certain variables to behave as constants, meaning we don’t expect these variables to actually change during an execution of the program.

Three constants are declared at the beginning of the program and given the names START_VAL, STOP_VAL, and STEP_VAL. To indicate to other people that these values are constants we write them in all caps with underscores separating each word.

"""
count_to_ten_documented
"""

from microbit import *         #import the microbit library

START_VAL = 1                  #set START_VAL to 1
STOP_VAL = 11                  #set STOP_VAL to 11
STEP_VAL = 1                   #set STEP_VAL to 1

#count from START_VAL to STOP_VAL incrementing by STEP_VAL
for counter in range(START_VAL, STOP_VAL, STEP_VAL):   
    display.scroll(counter)   #display the counter value

display.scroll("All Done!")   #display message when done

 

Documenting Code

Documenting code is the process of writing notes about what each part of the program does. You can help make your code self-documenting by picking variable names that help make the program more self-explanatory.   If you are thinking about working in a field that involves programming, it’s a good habit to start now. Why?

  • Folks who write code for a living, like software developers and robotics programmers, are usually under orders to document their code.
  • Other people might need to make updates to your code or use it for another project, and they need to understand what the code does.
  • Documented code can save you lots of time trying to remember what your code does, and how it does it, after you haven’t looked at it for a long time.

In addition to making your code easier to read, abstracting the code with variables and constants allow you to adjust an often-used value quickly and accurately by updating a single declaration. Trying to find and update each instance of an unnamed value by hand is an easy way to create bugs in your program.

  • Read through the program to see how variables and comments are formatted and used.
  • Open the script simple_decisions and document it, using the script count_to_ten_documented as an example.
  • Add a detailed description of the script, enclosing it with the title in a block comment.
  • Use special formatting to indicate that you intend the values of 89 and 42 to not change.
  • Add line comments to the right of each line.
  • Save your updated script.