Chapter 1 Documentation Tips

Pythonic Programming — by Dmitry Zinoviev (8 / 116)

👈 About the Reader | TOC | Hello, World! 👉

Software documentation is essential. A poorly documented program is hard to understand and, as a result, hard to maintain. Python is proud of being a self-documented language — which is not the same as a self-documenting language. You, as a programmer, are still in charge of developing the documentation.

Quality documentation begins with proper formatting, which Python, fortunately, enforces at the syntactic level. Quality documentation includes properly constructed identifiers (variable, function, method, class, and module names) and proper choice of quotation symbols for your strings. You will learn how to avoid “magic” (not explicitly clear) values. Finally, you will master the docstring mechanism that allows you to attach documentation to every Python code unit.

Writing documentation is a tedious process, but it is worth it — for the sake of the future readers of your code, including yourself.

👈 About the Reader | TOC | Hello, World! 👉

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.