如何在 Python 代码中包装和对齐注释？答案

【问题标题】：How to wrap and align comments in Python code?如何在 Python 代码中包装和对齐注释？
【发布时间】：2023-03-24 22:08:01
【问题描述】：

我正在尝试让我的 Python 代码看起来更易读。我读了style guide，但我不知道如何获得这样的东西

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)

或者这个

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

你如何包装评论并像这样对齐它们？你不只是输入一堆space，对吗？如果我编辑了代码，我是否必须手动重新对齐 cmets？

我使用 emacs 作为我的编辑器。

【问题讨论】：

如果你想这样做（这是有问题的），你肯定希望文件中的空格是空格。如果您只是询问如何编写 emacs 以便您不需要手动输入所有这些空格……那么，您可以将任何击键绑定到任何函数，但您需要准确定义该函数之前应该执行的操作有人可以告诉你怎么写……

标签： python emacs alignment comments

【解决方案1】：

我认为你根本不想要这个。 Lattyware 已经解释了第二种情况，但让我们看第一种：

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)

注释太长不适合内联，可以在代码上方转成block cmets，像这样：

# 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);

这似乎比右对齐的 cmets 更具可读性。它还为您提供更多空间。而且使用 emacs 肯定更容易（只需输入整个内容并 meta-Q 即可）。并且，在 PEP 8 中引用 Inline Comments：

谨慎使用内联 cmets。

内联注释是与语句在同一行的注释。

这是内联 cmets 样式指南的开端，它非常强烈地暗示，如果您尝试编写的内容超出同一行的容量，则应该使用块注释。

此外，当我们谈论 PEP 8 时：

“评论应该是完整的句子。”您的第一条评论需要句号。（是的，它还说“如果评论很短，可以省略末尾的句号”，但是您有一个 3 行 2 句的评论，所以这里不适用。）
“如果评论是一个短语或句子，它的第一个单词应该大写”。因此，请大写“Compute”（但不要大写“foo”，因为那是一个标识符）。
不要添加函数名称不好的注释，只需重命名函数即可。
去掉那个分号。

所以：

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

但是一旦你这样做了，你甚至都不需要评论。

事实上，这很常见。当您发现自己想知道如何打破评论的样式准则时，您可能应该询问如何重新组织代码以使其不需要所有这些 cmets。这并不总是可能的，但通常至少值得一试。

【讨论】：

谢谢，这些都是很好的建议。第一个代码是我在网上找到的一个示例，我认为它看起来不错。不。我应该坚持指南。
@LWZ：你在网上找到的任何行尾有分号的例子都可能是由比你了解的 Python 少的人写的，所以我不会把它当作模型......
大声笑我认为关于函数名的评论只是一些随机的例子来说明一点，我不认为 OP 实际上有那段代码

【解决方案2】：

你不应该这样做。第一个格式应该是这样的：

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

第二个：

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

【讨论】：

谢谢。这个简洁的答案本身就是“好看且可读”。

【解决方案3】：

我认为这两种情况截然不同。在第一种情况下，我会在制表符上使用空格，因为无论用户编辑器中的制表符宽度设置如何，您都希望 cmets 对齐。显然，如果你正常使用制表符缩进代码，使用制表符，直到你达到代码的水平，然后是空格。

想象一下使用标签：

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)

现在假设有人使用较短的制表符长度设置：

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)

不过，我认为您可能想用三引号字符串替换它：

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

在第二种情况下，我认为对齐 cmets 不会增加可读性，我只会将它们放在行尾。 PEP-8 建议不要对齐分配、dict 文字等... - 我认为这是对它的扩展。

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

【讨论】：

谢谢。我认为三引号要好得多。
“现在想象一下有人使用较短的制表符长度设置”。对我来说，这绝对不是理由。 Python 缩进通常是 4 个空格。更改该约定与以这种方式注释代码一样糟糕和不鼓励（或者可能更多）。对我来说，这听起来像是在说“不要这样做不是因为它是错误的，而是因为其他人可能会做更糟糕的事情”。
此外，tiple 引用，afaik 它应该只用于文档字符串，而不是随机 cmets。多行 cmets 通常简单地重复 #。在我看来，这是一个糟糕的设计选择，特别是因为大多数 IDE 在它们不是文档字符串时突出显示字符串的方式与 cmets 不同（并且更强）。
@J.C.Rocamonde 如果您使用制表符进行缩进，那么无论如何您都在使用 PEP-8。要点在于，如果您要缩进对齐，则应该使用通常使用的缩进系统，然后使用空格对齐。至于三重引号字符串，您似乎只是在争论“我还没有看到这个”，而不是因为它不好。文档字符串已经以相同的方式突出显示，所以我没有看到突出显示的问题。 PEP-257 明确谈论“发生在其他地方”的文档字符串并对其表示认可。
哦，好的，不知道文档字符串的那个，谢谢你的澄清

【解决方案4】：

尽管有使用替代方案的原因，如果您发现自己处于需要它的位置，比如注释用伪代码 Python 编写的证明行，您可以使用align-regexp：

M-x align-regexp RET  # RET

（在 # 符号前加一个空格）应该按照您的要求进行。它适用于当前选定的区域。

【讨论】：