GCP 2 - Describing your code

GCP 2 - Describing your code#

This file is adopted with modifications from GCP 2 - Describing your code by Geo-python

Binder

Another good coding practice (GCP) is describing your code. In a Jupyter notebook, text can take two basic forms:

  • Code comments: Text in codes to help user understand what the code is doing

  • Markdown text: Text in markdown cells to provides a broader view of the code or analysis

Providing code comments or markdown text makes is easier for you and other understand your code.

Code descriptions are a big part of why Jupyter notebooks are so powerful because you write scientific texts with embedded code cells to be able to perform calculations, analyze data and visualize your results. This powerful platform is an excellent open science tool that provides a clear means to reproduce your results on demand. Here you can find some examples.

For this course, comments serve an additional purpose. For us, comments make sure we understand what each line of our code does, and help the graders follow your thinking in the code.

This notebook provides examples of both below, along with some tips.

1. Code comments#

Code comments are text within your Python code that does not get executed. There are two types of code comments in Python, described below.

1.1 Line comments#

Line comments begin with the # character and everything to the right of that character will be ignored by the Python interpreter. These comments are most frequently used to describe single lines of code or a small group of related lines. Let’s have a look at an example.

# This is a line comment. It will be ignored when this cell is run

When you run the cell above, nothing happens. The # character indicates the line contains a comment and the Python interpreter simply skips over this line.

Let’s have a look at a few more examples.

# This list has the names of some observation stations in South Florida
station_names = [
    "Homestead",
    "Fort lauderdale",
    "Immokalee", 
]

print(station_names[-1])  # This prints the last value in the list station_names

Immokalee

# This is not needed for at this stage, so I'm commenting it out
# station_names.append("Belle Glade")

In the examples above you can see some of the ways in which line comments can be used in Python.

1.2 Block comments#

Block comments are similar to line comments in that they are embedded within your code and are not executed when a code cell is run. You can begin a line comment with three quotation marks ''' and end it with the same thing, three quotation marks '''. Everything within the groups of quotation marks will be ignored and it does not make any difference whether you use three single ''' or double """ quotation marks. Let’s see some examples.

""" This text will also be ignored.
Even if it is spread across multiple lines.
Cool! """

' This text will also be ignored.\nEven if it is spread across multiple lines.\nCool! '

""" The list below contains names of observation stations in South Florida.
More information and a complete list of stations can be found at 
https://fawn.ifas.ufl.edu/tour/location_info.php """
station_names = [
    "Homestead",
    "Fort lauderdale",
    "Immokalee", 
]

""" None of the code below is needed, commenting this out for now.
station_names.remove("Homestead")
station_names.pop(0)
station_names.append("Fort Myers")
station_names.append("Immokalee")
station_names.reverse()
"""
print(station_names)

['Homestead', 'Fort lauderdale', 'Immokalee']

In a future lesson you will be introduced to a common form of block comment called a docstring that can be used to provide information about certain parts of Python programs to the users.

2. Markdown text#

Markdown text is not a replacement for line or block comments in the code cells, but rather a place to provide a broader description of the code. Let’s see an example of the use of a Markdown cell below under the heading “Data source”.

Data source#

Data used in this example comprises observtion station:

  • names

  • locations

  • types

  • identification codes

These data are sourced from the Florida Automated Weather Network (FAWN) that was created in 1997 with a legislative appropriation for the University of Florida Institute of Food and Agricultural Sciences (UF/IFAS).FAWN was created to assist growers in making decisions related primarily to crop and landscape irrigation, freeze protection, and chemical application.

An example Python cell with select observation station names in South Florida is below. NOTE: These are only some of the observation stations in South Florida.

station_names = [
    "Homestead",
    "Fort lauderdale",
    "Immokalee", 
]

In the example above, you clearly see the benefit of the Markdown cells for providing nicely formatted text to support the code block beneath it. We can also embed images and other features that make the Jupyter notebook document a powerful tool for studying and learning. We’ll get more practice working with Markdown cells in the exercise for this week.

Contents