Frog frog recommendation: How to Write high-quality Python programs

How to Write high-quality Python Program Directory

1. CodeSpecifications
2. Blank Project template
3. Unit Test
4. Document
5. Package
6. Summary

Code Specification

First, read the following two specifications and gain an in-depth understanding.

• Officially recommended Python encoding style for the python community: pep8 Chinese Version
• Python coding style recommended by Google SOC: Chinese version of Google Python Style Guide

Writing standardized code is the first step in writing high-quality code and helps cultivate the habit of being careful.

To cultivate the habit of writing code, you can install the flake8 tool, which not only checks whether the code style conforms to the official recommendation (pep8 ), in addition, you can also find potential risks (using pyflakes for syntax analysis). What's more, you can also detect that some of your functions are too complex (the complexity of code circles, more importantly, you can set git commit before passing these checks.

Of course, specific operations need to be customized according to your own project, for example, you can ignore e501, w293.

Blank Project template

A good start is half the success. Write Python code from pyempty.

On GitHub, let's take a look at the Classic projects, Web. PY, flask, and pep8. Their project directories are standardized. I wrote this pyempty project based on the characteristics of some projects.

1. Readme. mdHere, I will describe your project introduction, Quick Start and other information. Although distutils requires that this file has no suffix, if the suffix is. md on GitHub, it can be directly converted to HTML display.
2. Changelog.txtThe change information of each part of the file storage program also has a fixed format. For more information, see changelog.txt of web.py.
3. Licenes.txtThe protocols used by your project are stored here. Do not write your own protocols.
4. Requirements.txtIf your project needs to depend on other third-party Python libraries, write a line here. It may be automatically installed during Pip install.
5. Setup. pyInstallation script, which will be detailed later
6. DocsIt stores your project documents, such as Outline Design, detailed design, maintenance documents, automatically generated pydoc documents, etc. We strongly recommend that you write documents in markdown format.
7. SRCThis directory stores the main code of the project module. Try not to put the Module Directory directly into the root directory. The module code directory can be specified in setup. py.
8. TestsThis directory stores all unit tests, performance test scripts, and unit test files with the prefix of test _, so that distutils will automatically package these files and usePython-M unittest discover-S./-P 'test _ *. py'-VThese tests can be executed directly.

Unit Test

 
Martin Fowler: "You shouldn't write a program before you know how to test the code. Once you have completed the program, the test code should also be completed. Unless the test is successful, you cannot think that you have compiled a program that can work. "
 

We have many reasons not to write unit tests. In the final analysis, we are lazy, although the Code is as follows:

 
Most studies have found that testing costs less than testing. A study by the NASA Software Engineering Lab found that the defects that can be detected hourly by reading the Code were about 80% higher than the tests (basili and Selby 1987 ). Later, an IBM study found that a check found that only 3.5 jobs were needed, while 15-25 work hours (Kaplan 1995) were required for testing ).
 

However, unit testing gives others the best evidence that your code has a high quality.

Okay. Read more:

1. In-depth python3.0: unit test-2. x is also applicable
2. Unit Testing Framework incomplete Chinese Version

Document

Agile development does not advocate or write any documents. without documents, there will be no inheritance or accumulation, and it will be very troublesome for rotation or new personnel to take over the task, therefore, I decided to write the following documents at least for each project:

1. Nalysis. model. mdThe outline design document is different from the readme. md file. This document should be written before the project development, and write down the project's functions, which are roughly divided into several modules and other overall project overview information.
2. Design. model. mdDetailed design documents, not too detailed, at least the project depends on what, who depends on this project, importantAlgorithmProcess description and overall code structure.
3. Maintain. mdMaintenance documentation, which I think is the most important? What logs are recorded for your service, which business indicators need to be monitored, how to restart, and which configuration items are available, your project is difficult to maintain.

The above documents are all project-wide documents and are not suitable for writing in docstring or watching. Therefore, there must be separate documents.

Package

Python has a dedicated module Packaging System distutils. You can use this mechanism to package your code and distribute it to pypi, so that anyone can use Pip or easy_install to install your module.

If you are developing an internal project, you can also use mypypi to set up a private pypi, and then release the major version of the project to the internal pypi, configuration Management Personnel and O & M personnel can easily pull code from pypi and install it to the test environment or production environment.

When releasing a major version, you must name the version and write a changelist. For details, refer to the related chapters of git pro. Remember the following commands.

 
Git tag-A v0.1-M 'my test tag' # name the major version, and name the taggit describe master # name the minor version. Git returns a string consisting of three parts: the version number of the last calibration, plus the number of submissions since that calibration, plus a piece of SHA-1 value git commit log -- no-merges master -- not v0.1 # To generate a version briefing, changelist
 

Python has its own packaging mechanism, so it is generally not usedGit ArchiveCommand.

Of course, it is more appropriate to use pypi to manage major versions. Many companies, such as small bug fixes and urgent releases, use git to pull code updates directly from the production environment, because git, SVN and so on can easily cancel an update and roll back to a certain position.

I have not figured out how to manage major version releases and urgent releases. You are welcome to join the discussion.

For more information about packaging, see the following link:

1. Python packaging Guide
2. Go deep into python3.0: Package the python class library
3. Python packaging: distributing specified files

Summary

The above is a summary of some recently learned things. You are welcome to discuss them together.