How to wrap and align comments in Python code?

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

Nonwithstanding the reasons to use alternatives, if you ever find yourself in a position where you need this, say for commenting the lines of a proof written in pseudocode-Python, you can use align-regexp:

M-x align-regexp RET  # RET

(put a space before the # sign) should do what you asked for. It works on the currently selected region.

Answer 2

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.

Answer 3

I would argue that the two cases are vastly different. In the first case, I would use spaces over tabs, as you want the comments to align regardless to tab width setting in the editor of the user. Obviously, if you use tabs for indentation of code normally, use tabs until you reach the level of the code, then spaces.

Imagine using tabs:

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) 

Now imagine someone uses a shorter setting for tab length:

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) 

I would argue, however, you might want to replace this with a triple quoted string instead:

"""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)

In the second case, I don't think aligning the comments adds to readability, I would just put them at the end of the line. PEP-8 recommends against aligning assignments, dict literals, etc... - and I would consider this an extension of that.

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

Answer 4

You should not do this. The first should be formatted 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)

And the second:

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