What is the significance of 'doc strings' in Python?

Issue related to: Core Python

Issue Link: https://www.reddit.com/r/learnpython/comments/g124za/what_is_the_significance_of_doc_strings/


I don’t understand the point of having doc strings when you can just enter comments with “#”. Am I missing something?


# comments are not executed by the Python compiler so we can use # comments in multiple ways – It can be used to remind us what specific parts of the program do or can be used for testing. In addition comments can be put in-line or on their own anywhere in the program.

For example:

# Define sharks variable as a list of strings
sharks = [‘hammerhead’, ‘great white’, ‘dogfish’, ‘frilled’, ‘bullhead’, ‘requiem’]# For loop that iterates over sharks list and prints each string item
for shark in sharks:

”’ ”’ Docstring are strings used by the Python compiler to create documentation automatically for your modules, classes, methods and functions. They should be put as the first statement after the declaration of a module, class, method or function. You can then use documentation generators such as Sphinx to auto generate a Docstring that can be presented on the web

For Example

“””This is a single line docstring”””

Which one you decide to choose depends on who is going to be reading using and debugging your program.

If your program is a large scale such as a library that will be used by many people then a Docstring would be mandatory . Suggestions brought up by IDEs after you type in a function are done using the Docstring. Furthermore developers can quickly refer to your Docstring to see what functions do and are offered

If your program is small and is going to primarily used by you then comments at different functions to remind you what it does would suffice.