In this lesson, you’ll see what makes a good comment. You’ll learn conventions for writing
- Block comments
- Inline comments and
- Docstrings
You’ll learn how to write block comments that span multiple paragraphs:
Python
def quadratic(a, b, c, x):
# Calculate the solution to a quadratic equation using the
# quadratic formula
#
# There are always two solutions to a quadratic equation,
# x_1 and x_2
x_1 = (- b+(b**2-4*a*c)**(1/2))
x_2 = (- b-(b**2-4*a*c)**(1/2))
return x_1, x_2
Next, you’ll see why inline comments can be unnecessary and distracting if they state the obvious. You’ll learn how to write useful inline comments without cluttering your code:
Python
# Don't do:
x = 'John Smith' # Student Name
# Do:
student_name = 'John Smith'
You’ll also cover how to write documentation strings:
Python
def quadratic(a, b, c, x):
"""Solve quadratic equation via the quadratic formula.
A quadratic equation has the following form:
ax**2 + bx + c = 0
There are always two solutions to a quadratic equation:
x_1 and x_2.
"""
x_1 = (- b+(b**2-4*a*c)**(1/2))
x_2 = (- b-(b**2-4*a*c)**(1/2))
return x_1, x_2
Ignat Domanov on July 2, 2020
side comment: both x_1 and x_2 in
should be divided by 2*a