See Python code comments from open source projects

Recently read a lot of code, also wrote a lot of code, so in the look and write found a lot of problems, really is a lot, at least from my understanding, there are a few places there is a lot of room for improvement, there are not ready to put all the problems listed, so the first to choose a more obvious to talk with you. Review of the success of the popular Open source project, in addition to functional requirements, documentation is also an essential part of the open-source project without good documentation is almost impossible to say is popular, because very few people will be because you said a sentence using my project can be silly not to slip autumn to use you. From my previous open source project, one of the big questions you might find is that the documentation is really not doing well.

Documents in the project I think that can be divided into direct documents and indirect documents two parts, the direct document is Readme/read the docs, such as the direct reading of the document, and the indirect document is a comment in the code. While others are reading your project, first of all, direct documentation allows you to have an intuitive understanding of your project, know what your project is about, what the approximate implementation idea/algorithm is, and the code comment is a reference that someone else is verifying that your project is really as good as your document says, So both of these documents are important.

In Python, because of the presence of docs comment, you can make these two documents one, in fact, it is to comment out into the document can be read directly, although this is somewhat idealistic, but to a certain extent, reduce the difficulty and complexity of writing documents. This article makes a brief summary of how to write such a Comment, and it is also an improvement to yourself.

Google Coding-style Guide

The students who play Python should know that Python does not have a code specification for the industry, and PEP8 these are not entirely good for our development to standardize and know the role. Instead, look at the code of many people now, found that Google coding style acceptance is higher, so, may wish to refer to a few more.

module annotations

In Python, each file is actually a self-contained module, so I call the file comment as a module comment, the module annotation is generally to explain what the module is for, and how to use the module and other information, and after the building of the tool has become the main content of the document. Let's take a look at requests's comments:

?

Can be found in fact this note is still relatively clear, can be divided into several parts, namely:

1. function Introduction
2. Using the Demo sample and Parameters/return values, etc.
3. Description of copyright, etc.

This is a relatively standardized note, as for the style of the annotation, we can refer to Restructuredtext Primer this note for practice.

Class Comment

Class comments are slightly more complicated, in addition to the necessary class descriptions and usage examples, you also need to describe the arguments to the class's awesome functions, because the Python constructor is __init__ , and we usually document the description of the class directly, so it's important to write it on the class! If your class has the necessary public properties that need to be exposed, you should also label it. We can refer to the example of Flask:

?

The previous voluminous had to write a lot of instructions, and then the parameters of the constructor were described later.

function comment

The comment of the function should be the most complicated, because we not only describe the function of function, but also pay attention to the function's parameter and return value, the parameter need to describe the meaning of the parameter, also describe the type of the parameter, the return value is same, so we also take a look at an example of celery:

?

There are only explanations of functions, caveats and return values, and we often use the following:

• Args
• Returns
• Raises

?

Building documents from source code

When we annotate our source code to 7788, think it is time to compile a document to see how the effect, then you should look at the following introduction!

Of course, I still refer to the practice of some popular projects, to see how people's documents are done, to tell the truth, I have seen so many projects in the document, Flask is indeed a good write, of course, Django is also good, but its documentation is too artificial modification, from the source of the restore degree is not so high. So here I take Flask as an example to see how open source projects are annotated and documented.

To understand the nature first try again, not too much trouble, will Flask source clone down, just need to use make docs , wait a moment, you will be the compilation version of Docs, by default you will get the HTML version, the location is in the directory of the source directory _build/html . However, look at Makefile again look at the docs table of contents You may be puzzled, because it docs has already placed the RST file, so this time the problem is how to extract files from the py file rst !

In fact, these problems are very simple for some tools, Flask with Sphinx, this tool is the Python world most open source projects favored, so also become a de facto document standard. The use of Sphinx allows us to easily solve two problems:

• Extracting Python annotations
• Document the Code

The operation process is just a two-sentence command to solve the problem:

• To extract the document comments from the code:sphinx-apidoc -F -o docs flask
• Convert the document to HTML form:sphinx-build -b html . _build/html
  • Or, on the basis of the first step, a bit more direct:make html

In this way, you will transform your previous efforts into a document that can be intuitively accepted! Here is an example that I have converted:

?

Many times we may not be very satisfied with the default converted documents, but it doesn't matter, we can edit the RST file after the first step, then adjust to our satisfaction, then make html , this will be much better!

Reference

1. Google Python Style Guide
2. Restructuredtext Primer

See Python code comments from open source projects