42, software directory structure

Why design a good directory structure?

"Design project directory structure" on and "code coding style", as is a personal matter of style. For specifications on this style, there is always two attitudes:

1. A class of students that this kind of personal style question "irrelevant." The reason is to make the program work just fine, the problem is not a matter of style.
2. The other students that better control of the standardization program structure, make the application more readable.

I am more biased in favor of the latter, because I was a direct victim of the former students thinking and behavior. I have been maintaining a very bad reading of the project, its implementation logic is not complicated, but it takes me a very long time to understand what it wants to express. From my personal project to improve the readability, maintainability requirements on high. "Project directory structure" actually belongs to the category of "readability and maintainability," we design a clear hierarchical directory structure, it is to achieve the following two points:

1. High readability: not familiar with the code for this project people, one can understand the directory structure, which is known startup script, where the test directory, where the configuration file, and so on. So very fast about this project.
2. High maintainability: The definition of a good organizational rules, defenders will be able to very clearly know which new files and code should be placed under any directory. The advantage is that, over time, the code / configuration size increases, the structure of the project will not be confused, still able to organize well.

So, I think, to keep a clear level directory structure is necessary. Not to mention a well-organized project directory, in fact, it is a very simple thing.

Directory organization

On how to organize a good Python project directory structure, there are already some consensus has been the directory structure. In Stackoverflow of this issue on, we can see the discussion of Python directory structure.

That said, there has been very good, and I do not intend to re-create the wheel cited a variety of different ways, and there I said my understanding and experience.

Assuming your project is named foo, I recommend comparing the most convenient directory structure like this will suffice:

Foo/
|-- bin/
|   |-- foo
|
|-- foo/
|   |-- tests/
|   |   |-- __init__.py
|   |   |-- test_main.py
|   |
|   |-- __init__.py
|   |-- main.py
|
|-- docs/
|   |-- conf.py
|   |-- abc.rst
|
|-- setup.py
|-- requirements.txt
|-- README

Explain briefly:

1. bin/: Some items stored in the executable file, named of course, you can script/also line the like.
2. foo/: Store all the project's source code. (1) all the source code modules, packages should be placed in this directory. Do not put the top-level directory. (2) its sub- tests/storage unit test code; inlet (3) program is preferably named main.py.
3. docs/: Store some documents.
4. setup.py: Installation, deployment, script packaged.
5. requirements.txt: Python package store a list of external software dependencies.
6. README: Project documentation.

In addition, there are a number of programs are given more and more content. For example LICENSE.txt, ChangeLog.txtfiles, etc., I have not listed here, because these things are mainly open source project when the need to use. If you want to write an open source software, how to organize the directory, you can refer to this article .

Here, then simply talk about my understanding of these directories and personal demands it.

About contents of README

I think this is that each project should have a file , the purpose is to be able to brief information of the project description, allowing readers to quickly understand the project.

It should be noted that the following matters:

1. The basic functions of the software localization, software.
2. The method of running code: installation environment, start commands.
3. A brief description of the use.
4. Code directory structure, a more detailed description can point the basic principles of software.
5. Frequently asked questions.

I think there are more than a few points is good README. In the early days of software development, because the development process is not clear or above may change, not necessarily to all the information will be complemented at the outset. But at the end of the project, is the need to write such a document.

Can refer to the source code Redis Readme wording, there is a clear but concise description of the source structure and function Redis.

About requirements.txt and setup.py

setup.py

In general, use setup.pypacking to manage code, installation and deployment issues. The industry standard is written in Python popular packaging tools setuptools to manage these things. This mode is commonly used open source projects. But here's the core idea of not using standardized tools to solve these problems, but said that a project must have a deployment tool to install , can be quickly and easily installed on a new machine on the environment, the code will be deployed and running stand up.

I stepped on this pit.

When I first came into contact with Python writing project, installation environment, deploy code, run the program the whole process is done manually, I encountered the following problems:

1. When the installation environment often forget to recently added a new Python package, the results of a run to the line, the program wrong.
2. Version of the Python package dependency problems, sometimes we used in the program is a version of the Python package, but the official has the latest package, installed by manually installing it may be wrong.
3. If you rely on a lot of packages, then one by one, these things depend very time-consuming installation.
4. New students started writing project, the program will be up and running very troublesome, because it may often forget how to install various dependencies.

setup.pyThese things can be automated together, improve efficiency and reduce the probability of error. "Complicated things automated, can automate things must be automated." Is a very good habit.

setuptools the document relatively large, new to the case, you may not find good entry point. Learning technology way is to see how others are using, you can refer to a Python Web framework, how the flask was written:  setup.py

Of course, the simple point write their own installation script ( deploy.sh) alternative setup.pyis also not a bad idea.

requirements.txt

The present document aims to:

1. Facilitate the development of software maintenance package dependencies. The process of developing new packages added to this list to avoid setup.pymissing installation package dependencies.
2. Convenience of the reader a clear project which uses Python package.

The file format is described in each row contains a packet-dependent, usually flask>=0.10this format, this format is required can be pipidentified, so that by simply  pip install -r requirements.txtto rely on all the Python packages are fitted. Specific Format Description:  Click here .

 

Usage on profile

Note that in the above directory structure, there is no will conf.pyon the source directory, but on the docs/directory.

Many projects use practices for the configuration file is:

1. Profiles written in python one or more files, such as conf.py. here
2. Project which module to use this configuration file directly through the import confuse of this configuration in code form.

I do not agree with this approach:

1. This makes it difficult to unit test (due to internal module dependencies external configuration)
2. On the other hand profile as the user interface to the control program, the path to the file should be specified freely by the user.
3. Bad reusability program components, such as through hard-coding all the code modules such that the modules are most dependent on conf.pythis file.

So, I think using the configuration and better way,

1. Configuration module is flexible configuration, is not affected by external profile.
2. The configuration program is also flexible control.

The idea is to be able to evidence, used and nginx mysql students know, nginx, mysql these programs can be freely specified user configuration.

Therefore, the code should not be directly import confused profile. Above directory structure conf.py, a sample configuration is given, not hard-coded configuration files directly referenced in the program. You can give main.pyto let the program read the contents of the specified configuration path configuration startup parameters way. Of course, where conf.pyyou can change a similar name, for example settings.py. Or you can use the content in other formats to write configuration files, such settings.yamllike.

 

Original link: https://www.cnblogs.com/alex3714/articles/5765046.html