How to properly comment functions in Python

Question

I would like advice on how I should structure my comments for functions. Is the description I currently have too in-depth?

The following code is for an algorithm that solves the n-queens problem.

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

If your code requires horizontal scroll, you're doing it wrong. Keep them short and sweet. — cs95
– cs95, Commented Mar 18, 2018 at 12:00
Did you read PEPs python.org/dev/peps/pep-0008 and python.org/dev/peps/pep-0257? — Alexey Dolgopolov
– Alexey Dolgopolov, Commented Mar 18, 2018 at 12:03
I think if you really need it very detail, just do it, you just need care about pep257 — atline
– atline, Commented Mar 18, 2018 at 12:04
Technically, this is a docstring rather than a comment, but agreed with above 3 suggestions. — jpp
– jpp, Commented Mar 18, 2018 at 12:34
Since it's for an assignment, I was thinking about if I should go in-depth on the detail. However by taking everyone's advice into consideration, would something like this be better for the main paragraph: Performs a hill climbing search on initial_board and returns a Board representing the goal state (local/global minimum). — Joshua
– Joshua, Commented Mar 18, 2018 at 12:51

Joshua · Accepted Answer · 2018-03-31 02:45:36Z

Thanks to Alexey's advice, I followed the PEPs and they provided great guidelines for commenting.

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

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

My resulting comment:

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

Collectives™ on Stack Overflow

How to properly comment functions in Python

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related