python - 如何在Python中正确注释函数

Question

我想了解如何构建函数注释。我目前的描述是否太深入？

以下代码是解决 n 皇后问题的算法。

def hill_climbing(initial_board):
    """
    While the current Board object has lower heuristic value successors, neighbour is randomly assigned to one.
    If the current Board's heuristic value is less than or equal to its neighbour's, the current Board object is
    returned. Else, the current variable is assigned the neighbour Board object and the while loop continues until
    either the current Board has no better successors, or current's h value is less than or equal to all of its
    successors.

    :param initial_board: A Board object with a randomly generated state, and successor_type of "best".
                          i.e. a start state
    :return: A Board object that has no further successors. i.e. a goal state (Local/Global Minimum)
    """
    current = initial_board
    while current.has_successors():
        neighbour = Board(current.get_random_successor(), "best")
        if neighbour.value() >= current.value():
            return current
        current = neighbour
    return current

Answer 1

感谢 Alexey 的建议，我遵循了 PEP，他们提供了很好的评论指南。

https://www.python.org/dev/peps/pep-0008/

https://www.python.org/dev/peps/pep-0257/

我的评论:

def hill_climbing(initial_board):
""" Hill Climbing Algorithm.

Performs a hill climbing search on initial_board and returns a Board
object representing a goal state (local/global minimum).

Attributes:
    current: A Board object
    neighbour: A Board object that is a successor of current

:param initial_board: A Board object with a randomly generated state, and successor_type of "best".
                      i.e. a start state
:return: A Board object that has no further successors. i.e. a goal state (Local/Global Minimum)
"""

current = initial_board
while current.has_successors():
    neighbour = Board(current.get_random_successor(), "best")
    if neighbour.value() >= current.value():
        return current
    current = neighbour
return current