I agree with the "remove the comments" suggestion. If you need a comment to describe each argument I see this as a naming problem more than a comment problem. You should have a nice docstring describing the purpose of a module. A nice docstring describing how to use a function. For a class you should document each visible attribute. After that, I don't think good code should have many comments. Code should be obvious. If you find yourself having to comment the code to make the meaning clear, take some time to think about ways to improve the code. Well documented confusing code is still confusing code.
Using named arguments goes a long way towards clearing any confusion about function arguments. This is a function I wrote for a Connect 4 game.
def drop(column:int, player:int)->tuple[int, int]:
'''Drop player's marker in column. Marker falls to first open row.
return resting spot.
Arguments:
column : Column chosen to play the marker. 0..COLUMNS-1
player : Player 0 or 1
Returns
row and column where marker is located or None if
column is full.
'''
for row in range(ROWS):
if BOARD[column][row] is EMPTY:
BOARD[column][row] = player
return(column, row)
return None
From an interactive environment I can ask to see the documentation for this function.
Output:
>>> help(drop)
Help on function drop in module __main__:
drop(column: int, player: int) -> tuple
Drop player's marker in column. Marker falls to first open row.
return resting spot.
Arguments:
column : Column chosen to play the marker. 0..COLUMNS-1
player : Player 0 or 1
Returns
row and column where marker is located or None if
column is full.
The function is called like this in the code:
while True:
try:
col = int(input(f'{MARKERS[player]}: '))-1
except ValueError:
print(f'Enter integer [1:{COLUMNS}]')
else:
if spot := drop(column=col, player=player):
return spot
print(f'{col} is full')
There is no need to comment the arguments because they are obvious. col is the column argument and player is the player argument. If I want to find out what these arguments do I should look at the documentation for the drop() function, not some possibly incorrect comments where the function is used.