From 68fc11453ae12f890255564f016c44e32da6a0b7 Mon Sep 17 00:00:00 2001 From: guibog Date: Wed, 25 Apr 2012 23:17:40 +0800 Subject: [PATCH] Add on documentation and comments --- docs/writing/documentation.rst | 124 ++++++++++++++++++++++++++++++++- 1 file changed, 122 insertions(+), 2 deletions(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 7ec1ce2..b27f8da 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -1,8 +1,128 @@ Documenting Your Code ===================== -Documenting your code is extremely important. It is debatably even -more important than testing. +With readability of the code being a main focus for Python developers, proper +commenting is naturally important. Some best practice apply to code comments +and project documents, depending on the scope of the project. + +Project documents +----------------- + +A README file at the root directory give general information to the users and +the maintainers. It should be raw text or written in some very easy to read +markup, such as reStructuredText and Markdown. It should contain a few lines +explaining the purpose of the project or the library (without assuming the user +knows anything about the project), the url of the main source for the software, +and some basic credit information. This file is the main entry point for +readers of the code. + +An INSTALL file is less often necessary with python, except if the dependencies +are complex or unusual, or if some C modules need to be compiled before use. +The installation instructions are often reduced to one command, such as ``pip +install module`` or ``python setup.py install`` and added to the README file. + +A LICENSE file should always be present and specify the license under which the +software is made available to the public. + +A TODO file or a TODO section in README should list the planned modifications +of the code. + +A CHANGELOG file or section in README should compile a short overview of the +changes in the code base for the latest versions. + +Documentation +------------- + +As the project or library reaches a certain level of complexity, it may require +a fuller documentation, which can be of different flavors: + +The introduction may show a very short overview of what can be done with the +product, using one or two extremely simplified use cases. + +The tutorials will show in more details some main use cases. The reader will +follow a step-by-step procedure to set-up a working prototype. + +The API reference, which is often generated automatically from the code, will +list all publicly available interfaces, their parameters and their return +values, with an explanation of their use. + +Some documents intended for developers might give guidance about code +convention and general design decision of the project. + +Comments +-------- + +Comments are written directly inside the code, either using the hash sign (#) +or a docstring_. + +Finding the correct balance between undocumented code and verbose and useless +comment boilerplates is difficult, and is the subject of heated discussion +among developers. + +The following guidelines seem to be most commonly agreed upon: + +**Wrong or outdated comments are worse than no comments at all.** Following the +saying that it is better, on a boat, to know that we do not know were we are +than to wrongly believe we know where we are, wrong or outdated comments can be +misleading for the maintainers, slow down considerably bug hunting or +refactoring, and then, when discovered wrong, they will throw suspicion on all +other comments in the code, regardless of their individual correctness. + +**No need comments for perfect code...** An hypothetical perfectly readable +code, with a crystal clear logic stream, expressive variable and function +names, orthogonal segmentation passing exactly between the flesh and the bones, +and no implicit assumptions of any kind, would not require any comment at all. +When striving for coding excellence, it is useful to see any existing comment, +or any feeling of a need for a comment, as the sign that the code do not +express clearly enough its intent and can be improved. + +**.. but no code is perfect.** Perfect code is a chimere, it exists only in +our dreams. In real life, a code base is full of trade offs, and comments are +often needed in the most difficult parts. Moreover, any special case, any +obscure hack, any monkey patch and any ugly workaround MUST be signaled and +explained by a proper comment. This should be enforced by the law! + +**TODOs** are special comments that a developer write as a reminder for later +use. It is said that its original intent was that someone might, one day, +search for the string "TODO" in the code base and actually roll their sleeves +and start *to do the TODOs*. There is no avalaible record that it ever +happened. However, TODOs comment are still very useful, because they mark the +current limits of the code, and it is not unlikely that, when required to add a +new behavior to the actual code, looking at the TODOs will show where to start. + +**Do not use triple-quote strings to comment code.** A common operation when +modifiying code is to comment out some lines or even a full function or class +definition. This can be done by adding triple-quotes around the code block to +be skipped, but this is not a good pratice, because line-oriented command-line +tools such as ``grep`` will not be aware that the commented code is inactive. +It is better to add hashes at the proper indentation level for every commented +line. Good editors allow to do this with few keystrokes (ctrl-v on Vim). + +**Bad** + +.. code-block:: python + + def tricky_function(): + ''' + if foo: + do_bar() + ''' + return baz + + def tricky_function(): + #if foo: + #do_bar() + return baz + +**Good** + +.. code-block:: python + + def tricky_function(): + #if foo: + # do_bar() + return baz + The Basics