: Re: When documenting Python, when should I use docstrings and when should I use comments? Python programming language provides two mechanisms for documenting a function, a module or a class: Comments

@RJPawlick285

Vote Up Vote Down

Code comments and docstrings have different purposes and audiences:

Developers write docstrings to describe the function's behaviour. Other developers, who use this function, read docstrings to find about the meaning of parameters, the pre- and post-conditions, possible exceptions etc.

If you're writing an API, you may want to publish docstrings as a part of documentation, but have your code and code comments private.
Developers write comments to describe the code's inner logic, when this logic isn't clear from just reading the code. The audience is themselves and other developers, who will modify this function in the future.

(0)

Login to post a comment!