4

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.

Improve this question
1
  • If you want to do this at all (which is questionable), you definitely want the spaces in the file to be spaces. If you're just asking how to program emacs so you don't need to type all those spaces manually… well, you can bind any keystroke to any function, but you'll need to define exactly what that function is supposed to do before someone can tell you how to write it… Commented Jan 18, 2013 at 23:34

4 Answers 4

Reset to default
9

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.

Improve this answer
Sign up to request clarification or add additional context in comments.

3 Comments

Thanks, these are good suggestions. This first code is one example I found online and I thought it looked good. Nah. I should just stick with the guide.
@LWZ: Any example you found online that has semicolons at line endings was probably written by someone who knows less Python than you, so I wouldn't take it as a model…
lol i think the comment about the function name was just some random example to make a point, i dont think the OP actually had that piece of code
3

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
Improve this answer

1 Comment

Thank you. This concise answer by itself is "great looking and readable".
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
Improve this answer

5 Comments

Thank you. I think the triple quote is much better.
"Now imagine someone uses a shorter setting for tab length". To me, that is definitely not a reason. Python indentation is conventionally 4 spaces. Changing that convention is as bad and discouraged (or probably way more) as commenting code that way. To me, sounds like saying "do not do this not because it's wrong but because someone else might do something even worse".
Additionally, the tiple quote, afaik it should only be used in that manner for docstrings, not for random comments. Multi-line comments conventionally simply repeat #. In my opinion it is a bad design choice, especially because most IDEs highlight strings differently (and stronger) to comments when they are not docstrings.
@J.C.Rocamonde If you are using tabs for indentation, you are breaking with PEP-8 anyway. The point stands that if you are indenting for alignment, you should be using the same system for indentation you normally use, then using spaces to align. As to the triple quoted string, you seem to just be arguing "I haven't seen this" rather than any reason it's bad. Docstrings are already highlighted the same way, so I don't see the highlighting issue. PEP-257 explicitly talks about docstrings "occurring elsewhere" and endorses it.
Oh, ok didn’t know about that of the docstrings, thank you for clarifying
0

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.

Improve this answer

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.