Question

对于Python代码PEP 257提供了使用docstrings来记录结构实体的约定：包，模块，函数，类，方法。

这涵盖了几乎所有内容。 StackOverflow关于如何评论Python代码的问题总是引出使用docstrings的答案。

这会留下什么评论？ Pythonic方法是专门使用docstrings而从不使用注释吗？或者他们有一些地方？

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

Answer 1

Doc-strings =使用您的功能的人的信息
内联注释=解释代码编写方式的原因。

请参阅requests library，了解适当使用评论的项目的一个很好的示例。

何时使用Doc-Strings

良好的文档字符串提供了在阅读Python文档时通常会看到的相同类型的信息。他们解释函数的作用，描述参数，如果返回某些内容，则应该提及。 Doc-strings还应该提到调用函数时可能发生的任何副作用。

思考文档字符串的一种方法是考虑在某些在线文档中显示该函数时要显示的信息。像Sphinx这样的程序可以根据文档字符串自动生成文档。

何时使用评论

另一方面，评论解释了令人困惑的代码片段。他们的目的是帮助那些正在进行错误修复的人，或者对代码进行更改以了解您的代码正在做什么。它们应该用于帮助解释仅通过查看它们而不是不言自明的代码行。

实施例

以下面的改组算法为例。请注意，注释的重点是解释算法的工作原理，而不是每行代码的作用。我们知道如何阅读代码，但评论中的信息对于任何查看代码的人来说都是有用的信息。另一方面，doc-string提供了所有需要使用shuffle函数的人都想知道的信息。他们不关心算法的内部。他们关心shuffle函数的输入和输出。

def shuffle(artist_song_dict):
    """ Shuffles songs in a semi-random fashion while keeping songs by the same artist spread out, as described in
    https://labs.spotify.com/2014/02/28/how-to-shuffle-songs/
    artist_song_dict must be a dictionary where the keys equal the artist names and the values are an iterable of each artist's songs
    A list of shuffled songs is returned
    """
    lineup = {} #each song will be stored in this dictionary with a value between 0 and 1 representing the song's position in the lineup
    variation = .3
    for artist in artist_song_dict:
        songs = artist_song_dict[artist]
        random.shuffle(songs)

        # Distance between songs in the lineup, if we were to space the songs out evenly
        spread = 1/len(songs)

        # This is reffered to as the offset in the article, but I found this has a different purpose than what the article says.
        # Without this random variation, the number of songs an artists has in the lineup affects the probablity that their songs
        # will appear first (or sooner/later) in the lineup versus other artists
        artist_variation = random.uniform(0, spread-variation)

        for i, song in enumerate(songs):
            # We want to add some randomization to the lineup, but not too much, 
            # otherwise, songs by the same artists could be played twice.
            # The article recommends adding a 30% variation to each song
            song_variation = random.uniform(0, spread*variation)

            # Assign this song the next evenly spaced spot in the lineup plus our variations
            lineup[song] = i*(spread) + artist_variation + song_variation

    return sorted(lineup, key=lineup.get)

内联评论与阻止评论

内联评论看起来像这样

x = x + 1                 # Compensate for border

虽然块评论看起来像这样

# Compensate for border.  These comments
# often cover multiple lines.
x = x + 1

两者都是有效的评论形式。我只是想我会指出有两种形式的评论。 PEP 8特别says谨慎使用内联评论。我相信他们正在反对使用注释来解释每一行代码如何工作的不当使用。您经常在教程和SO中看到这一点，但在实践中，您不应该评论自我解释的代码。

Answer 2

Python PEP8有一个关于评论的部分。简而言之：

谨慎使用内联评论。

内联注释是与语句在同一行的注释。内联注释应与语句中至少两个空格分隔。它们应该以＃和单个空格开头。

内联评论是不必要的，如果他们陈述显而易见的话，实际上会分散注意力。

对于区块评论：

块注释通常适用于跟随它们的一些（或所有）代码，并缩进到与该代码相同的级别。块注释的每一行都以＃和单个空格开头（除非它是注释中的缩进文本）。

块注释中的段落由包含单个＃。
的行分隔

正确使用评论？

2 个答案:

何时使用Doc-Strings

何时使用评论

实施例

内联评论与阻止评论