The correct way to do it is to provide a docstring. That way, help(add) will also spit out your comment.
def add(self):
"""Create a new user.
Line 2 of comment...
And so on...
"""
That's three double quotes to open the comment and another three double quotes to end it. You can also use any valid Python string. It doesn't need to be multiline and double quotes can be replaced by single quotes.
See: PEP 257
Answer from Chinmay Kanchi on Stack OverflowThe correct way to do it is to provide a docstring. That way, help(add) will also spit out your comment.
def add(self):
"""Create a new user.
Line 2 of comment...
And so on...
"""
That's three double quotes to open the comment and another three double quotes to end it. You can also use any valid Python string. It doesn't need to be multiline and double quotes can be replaced by single quotes.
See: PEP 257
Use docstrings.
This is the built-in suggested convention in PyCharm for describing function using docstring comments:
def test_function(p1, p2, p3):
"""
test_function does blah blah blah.
:param p1: describe about parameter p1
:param p2: describe about parameter p2
:param p3: describe about parameter p3
:return: describe what it returns
"""
pass
Comment Etiquette
What is the proper way to comment code in Python? - Stack Overflow
Comment conventions in python - Stack Overflow
"Essential Contextual Code Commenting" guideline for (concisely) commenting code - Ideas - Discussions on Python.org
Videos
So I feel a little stupid. I wouldn't call myself a complete beginner anymore, and I'm somewhat able to work my way around python and its libraries, yet I'm baffled by something simple: How the HECK do I comment stuff correctly. I've been programming for a couple of years now, am not only self-taught, but also went to a school that taught me a lot about C#, Databases - the basics. Yet what I never learned was how to comment correctly, how to correctly abbreviate my comments and how to not include essays of unneeded comments, that turn the whole code into 2x the length it needs to be.
I recently came across some of my first projects, in which we were supposed to create a short Rock-Paper-Scissors game and found this:
while game_is_running:
# any returns True if any of the conditions in the list are True
if any([wins, losses, ties]) is False:
print('Welcome to this short game.')And some more examples of code from other projects, this time a Tic-Tac-Toe game:
# print the whole game board def print_game_board(board):
# checks if one of the win conditions has been fullfilled after every input win_condition()
There are more examples but these are the ones that stuck out to me as unecessary.
So my question is simple: How much is too much.
I kind of feel dumb for even asking, but heck I'm here to learn as are most people.
I don't know if this represents the "community standard" but here are Google's Python style guides (as they relate to comments). Specifically classes:
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."""
When in doubt, look at the standard library for a model.
Here's an excerpt from the timeit module (written by Guido van Rossum himself):
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)
These are not comments, they are docstrings. Python allows you to define multi-line strings using triplets of either apostrophes or quotation marks, but PEP 257 recommends using the quotation marks with docstrings for consistency. It has no effect on the contents of the string, however.
It's a matter of preference. I would say it's more common to see double quotes with triple-quoted strings, especially when they're used as docstrings, but there's no functional difference between the two.
The method of documentation I learned in school is to list a function name, description, parameters, return type, and exceptions. It's serviceable, but a tad verbose and prone to redundancy. What do you recommend?
I am documenting the code for my new password manager. Here is the source on Github.