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

【问题标题】：What is the proper way to comment code in Python?在 Python 中注释代码的正确方法是什么？
【发布时间】：2012-11-30 18:20:58
【问题描述】：

我正在阅读 PEP8 和 StackOverflow 上的一些问题，但我想知道 cmets 之间的空格：

假设我有这个代码：

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"

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

【问题讨论】：

我认为您当前的间距很好......还有什么构成专家？
专家指的是某公司的招聘经理
他们可能不是专家……很多时候雇主愿意将你塑造成他们想要的样子……他们希望看到的是你掌握了 Python 的概念和原理…… . 并且您知道编译与解释等之间的一些差异。

标签： python comments

【解决方案1】：

我不知道这是否代表“社区标准”，但这里是Google's Python style guides（因为它们与 cmets 有关）。具体类：

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

【讨论】：

【解决方案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)

【讨论】：

【解决方案3】：

来自 Python 之禅：“可读性很重要。” 您的团队认为最易读的就是我会做的事情。

【讨论】：

一般来说，但有时它的 python 大众（而不是你个人）发现更具可读性（我给了你+1，因为总的来说这是真的）
我经常发现没有 cmets 我的代码可读性较差，因为我已经知道它的作用，但我觉得这并不意味着我不应该包含 cmets。
我不同意你喜欢的是最好的。我曾与遵循奇怪标准（例如三个空格缩进）的人一起工作。他们喜欢他们的代码。小组中没有其他人可以看到它。
TBH 我很少在我的 python 中包含 cmets ...我使用自我记录的变量/函数名称，这通常就足够了 ...也就是说我可能不会展示我的无注释代码 ..
可能...但是我们当中有多少人实际上拥有 Python 社区已经看到/将永远看到的代码？如果我能读懂它并且我的同事没有对我发牢骚，我觉得这就足够了。是的，我从来没有遇到过不向同事表达想法的程序员：D

【解决方案4】：

不要给出sn-ps，而是使用sphinx查看最常用的CPython并将文档与代码进行比较。

因为注释就在代码中，所以文档永远不会不同步。

【讨论】：