Formatting Python Comments

Writing Beautiful Pythonic Code With PEP 8 Joe Tatusko 04:40

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

00:00 Comments are how you document your code as it’s written to help others and yourself understand why things are the way they are. A good comment should explain exactly why something is the way it is and why it’s where it is. Like code, there’s a specific style where you should limit line lengths to 72 characters and use complete sentences starting with capital letters.

00:22 You’re writing for a human to understand, so keep that in mind. This being said, if it’s possible to write your code in a way that’s so clear that it doesn’t need comments, you should always default to that.

00:33 I tend to use the most comments when I’m using a new library or set of functions, because there’s a good chance once I learn about them a little more, I’ll be using them in a different way in the future. In this video, we’re going to talk about block comments, inline comments, and docstrings.

00:49 First, let’s talk about block comments. These are the traditional comments you may think of, where they describe a couple of lines of code around them. When you’re styling a block comment, indent them to the same line of code you’re at, start each line with a hash symbol or pound character (#), followed by a single space. So in this case, the comment is just saying what this function does, where it loops over i ten times and prints out the value of i followed by a newline character, right here.

01:20 If you need to use multiple paragraphs, that’s okay. Just separate each paragraph with a blank line that still includes a hash symbol or a pound symbol. So, you don’t want to do something like that.

01:31 Keeping a pound symbol here makes sure that it’s clear that this comment is all together and not two separate comments. Feel free to use block comments as much as possible.

01:41 They can really help with understanding what’s going on in your script.

01:52 Next, we have inline comments. These are a little bit different from block comments in that you don’t want to use these too often. They’re placed in the same line as the code they describe, so it can be very easy to add way too many of these to your scripts.

02:06 They can be good reminders or explain to others why a certain line of code is necessary. When adding an inline comment, make sure they’re at least two spaces away from the code and then do the same thing as a block comment where you use one hash symbol and a space.

02:23 Going back to making your code itself readable, don’t try to use an inline comment to explain something that can be fixed by using a better naming convention, like here. Rather than explaining now that x is equal to the student name, you should just make a variable called student_name and set that equal to the value that you want.

02:47 Another thing you don’t want to do is explain the obvious, like here, where this clearly initializes an empty list and this clearly multiplies x by 5.

02:58 Doing this can really clutter your code and if you read through code reviews on different forums, it’s a very common constructive criticism.

03:09 Finally, we have documentation strings, or docstrings. Docstrings are really cool and should be placed on the first line of any function, class, method, or module.

03:20 They’re used to explain why that block of code is present and are wrapped in three double quotation characters ("""). If you need multiple lines, put the closing quotes on their own line. So here, for quadratic_two(), you can see that this explains exactly why this function is written the way it is. And the reason I wrote this as quadratic_two(), is because the first one was quadratic().

03:44 And if you’ll note here, I get a tooltip that kind of tells me what’s going on with the variables. And that’s helpful, but in this case—and what you’ll see in a lot of editors—is if you do a docstring, you’ll actually have your docstring pop up in a tooltip.

04:00 This can be very helpful to a developer trying to use your code. If you’re able to fit the entire docstring on one line, you can put the closing triple quotes on the same line as the docstring.

04:11 And that’s it! That’s the basics of comments for PEP 8.

04:15 Feel free to look up PEP 8 if you want to see some more details on this, particularly around documentation strings, which has an entire PEP called PEP 257 that’s just focused on docstrings. For now, though, you should be in a good spot to start documenting your code.

04:34 In the next video, you’ll learn how to use whitespace in expressions and statements. Thanks for watching.

Ignat Domanov on July 2, 2020

side comment: both x_1 and x_2 in

x_1 = (- b+(b**2-4*a*c)**(1/2))
x_2 = (- b-(b**2-4*a*c)**(1/2))

should be divided by 2*a

Become a Member to join the conversation.