在Python中注释代码的正确方法是什么？

Question

我正在阅读 PEP8 和 Stack Overflow 上的一些问题，但我想知道注释之间的空格：

假设我有这个代码：

class MyBrowser(QWebPage):
    ''' Settings for the browser.'''

    def __init__(self):
        QWebPage.__init__(self)
        # Specifies whether images are automatically loaded in web pages.
        self.settings().setAttribute(QWebSettings.AutoLoadImages, True)

    def userAgentForUrl(self, url):
        ''' Returns a User Agent that will be seen by the website. '''
        return "Mozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/537.15 (KHTML, like Gecko) Chrome/24.0.1295.0 Safari/537.15"

在注释和实际代码之间放置空行的最 Pythonic 方式是什么？我想向一些专家展示我的程序。并希望我的代码看起来更专业。

Answer 1

我不知道这是否代表“社区标准”，但这里有 Google 的 Python 风格指南（因为它们与评论相关）。 具体课程：

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

Answer 2

如有疑问，请查看标准库中的模型。

以下是 timeit 模块的摘录（由 Guido van Rossum 本人编写）：

def print_exc(self, file=None):
    """Helper to print a traceback from the timed code.

    Typical use:

        t = Timer(...)       # outside the try/except
        try:
            t.timeit(...)    # or t.repeat(...)
        except:
            t.print_exc()

    The advantage over the standard traceback is that source lines
    in the compiled template will be displayed.

    The optional file argument directs where the traceback is
    sent; it defaults to sys.stderr.
    """
    import linecache, traceback
    if self.src is not None:
        linecache.cache[dummy_src_name] = (len(self.src),
                                           None,
                                           self.src.split("\n"),
                                           dummy_src_name)
    # else the source is already stored somewhere else

    traceback.print_exc(file=file)

Answer 3

来自 Python 之禅：“可读性很重要。”无论你的团队认为最具可读性，我都会做。

Answer 4

不要提供代码片段，而是使用 sphinx 查看最常用的 CPython 并将文档与代码进行比较。

• difflib — 计算增量的助手
• CPython，文件 difflib.py

文档永远不会不同步，因为注释就位于代码内部。

Answer 5

我刚刚读完你的文章，哇，太棒了！干得好！顺便说一句，如果您愿意的话，我很乐意分享一些有关我们高级 [Python 培训][1] 计划的内容。非常感谢！”

https://ihubtalent.com/full-stack-python-training/