Tip 8 Do Not Misuse Docstrings

Pythonic Programming — by Dmitry Zinoviev (16 / 116)

👈 Self-Document Your Code | TOC | Let input() Speak for Itself 👉

★2.7, 3.4+ Docstrings are a form of documentation, but you should use them only to describe the purpose of having objects and the way of using them. For everything else, such as explaining the implementation detail and design choices, there are comments.

​ ​# This is a comment​
​ 
​ ​'''​
​ ​This is not a comment​
​ ​'''​
​ 
​ ​'This is not a comment, either'​

Do not use unassigned strings as general comments. At the time of code writing, integrated development environments (IDEs) and stand-alone editors do not highlight them as comments, making them harder to spot. At runtime, the interpreter may need to spend time constructing the useless string objects. The latter is not a concern if your interpreter knows how to optimize string literals, but in general, this may be an issue.

The Zen of Python says: “There should be one — and preferably only one — obvious way to do it.” Comments are for commenting.

👈 Self-Document Your Code | TOC | Let input() Speak for Itself 👉

Pythonic Programming by Dmitry Zinoviev can be purchased in other book formats directly from the Pragmatic Programmers. If you notice a code error or formatting mistake, please let us know here so that we can fix it.