Question

I’m trying to make my Python code look more readable. I read the style guide but I don’t know how to get something like this

x = foo(x);  # compute the value of the next prime number
             # that is larger than x  (foo is a really bad 
             # choice for this function's name) 

Or this

x = x + 1                 # Compensate for border
some other code           # some other comment

How do you wrap the comment and align them like this? You don’t just type a bunch of space, do you? What if I edited the code, do I have to realign the comments manually?

I’m using emacs as my editor.

Answer 1

I don’t think you want this at all. Lattyware already explained the second case, but let’s look at the first:

x = foo(x);  # compute the value of the next prime number
             # that is larger than x  (foo is a really bad 
             # choice for this function's name) 

Comments that are too long to fit in-line can be turned into block comments above the code, like this:

# compute the value of the next prime number that is larger than
# x (foo is a really bad choice for this function's name)
x = foo(x);

That seems more readable than the right-aligned comments. It also gives you more room. And it’s definitely easier with emacs (just type the whole thing and meta-Q it). And, quoting Inline Comments in PEP 8:

Use inline comments sparingly.

An inline comment is a comment on the same line as a statement.

This is the very beginning of the style guide for inline comments, and it implies pretty strongly that if you’re trying to write more than you can fit on the same line, you should be using a block comment instead.

Also, while we’re talking about PEP 8:

• "Comments should be complete sentences." Your first comment needs periods. (Yes, it also says "If a comment is short, the period at the end can be omitted", but you have a 3-line 2-sentence comment, so that doesn’t apply here.)
• " If a comment is a phrase or sentence, its first word should be capitalized". So, capitalize "Compute" (but not "foo", because that’s an identifier).
• Don’t add a comment that the function’s name is bad, just rename the function.
• Get rid of that semicolon.

So:

# Compute the value of the next prime number that is larger than x.
x = next_larger_prime(x)

But once you’ve done that, you don’t even need the comment.

And in fact, that’s pretty common. When you find yourself wondering how to break the style guidelines on commenting, you should probably instead by asking how to reorganize the code so it doesn’t need all those comments. It’s not always possible, but it’s usually worth at least trying.