Why should we design a good directory structure?

When designing a website, you should create a folder on your computer hard drive in advance as a starting point for your work, and then create several subfolders under the folder to form a reasonable directory structure so that different types of The files are stored on the site.
The structure of the directory is an issue that is easily overlooked in website construction. Beginners often rarely plan and create subdirectories at will. Even the directory name is easy to find. Afterwards, even they forget why this directory was created and prepared. What type of files are stored. Strictly speaking, visitors will not have a clear feeling about the quality of the directory structure, but it will have an important impact on the maintenance of the website itself and the expansion and transplantation of future content.

Why should we design the directory structure?

"Designing the project directory structure" is the same as "coding style" "Same, it's a matter of personal style. There have always been two attitudes towards this style norm:

　1. One type of students believes that this personal style issue is "irrelevant". The reason is that as long as the program can work, style issues are not a problem at all;

2. Another type of students believe that standardization can better control the program structure and make the program have higher quality. Readability;

I am more inclined to the latter, because I am a direct victim of the former class of students’ thoughts and behaviors. I once maintained a project that was very difficult to read. Its implementation logic was not complicated, but it took me a very long time to understand what it wanted to express. Since then, I personally have very high requirements for improving the readability and maintainability of the project. "Project directory structure" actually belongs to the category of "readability and maintainability". We design a clear-level directory structure to achieve the following two points:

　1. High readability: People who are not familiar with the code of this project can understand the directory structure at a glance and know which program startup script is, where is the test directory, where is the configuration file, etc. So you can understand the project very quickly;

2. High maintainability: After defining the organizational rules, the maintainer can clearly know which new files and codes should be added In what directory should it be placed? The benefit is that over time, as the size of the code/configuration increases, the project structure does not become cluttered and remains well organized.

Therefore, I think it is necessary to maintain a clear hierarchical directory structure. What's more, organizing a good project directory is actually a very simple matter.

Directory organization method

About how to organize a better Python project directory structure, some information has been obtained Consensus directory structure. In this question on Stackoverflow, you can see everyone’s discussion on the Python directory structure.

What is said here is already very good. I am not going to reinvent the wheel and list various methods. Here I will talk about my understanding and experience.

Assuming your project is named foo, I suggest that the most convenient and quick directory structure is enough:

　Foo /

|-- bin/

## |-- foo

## |

## |-- foo/

##　　||-- tests/

##　　　|||-- __init__.py

　　||||-- test_main.py

　　| | 　 |-- __init__.py

##　 |-- main.py

##　|

|-- docs/

##　 |-- conf.py

　　| |-- abc.rst

##　　| #　|-- setup.py

##　|-- requirements.txt

　| -- README

A brief explanation:

1.bin/: Some storage options for the project Execution file, of course you can name it like

script/

;

　2.foo/: stores all the source code of the project . (1) All modules and packages in the source code should be placed in this directory. Do not place it in the top directory. (2) Its subdirectory tests/ stores unit test code; (3) The program entry is best named main.py;

3.docs/: Store some documents; 4.

setup.py

: Installation, deployment, and packaging scripts;　5.

requirements.txt

: List of external Python packages that store software dependencies;　6.

README

: Project description file. In addition, there are some plans that provide more content. For example,

LICENSE.txt

, ChangeLog.txt files, etc., I have not listed them here, because these things are mainly needed when the project is open source. If you want to write an open source software and how to organize the directories, you can refer to this article;

Next, let me briefly talk about my understanding of these directories and personal requirements. 　About the content of README

##　I think this is a file that every project should have

, the purpose is to briefly describe the information of the project and allow readers to quickly understand the project.

It needs to explain the following matters:

1. Software positioning, basic functions of the software;

　2. Methods of running the code: installation environment, startup commands, etc.;

　3. Brief instructions for use;

　4 .Code directory structure description, more detailed explanation of the basic principles of the software;

　5. Description of frequently asked questions.

I think the above points are a better

README. In the early stages of software development, since the above content may be unclear or change during the development process, it is not necessary to complete all the information at the beginning. But when the project is completed, such a document needs to be written.

You can refer to the writing method of Readme in the Redis source code, which briefly but clearly describes the Redis function and source code structure.

About requirements.txt and setup.py

Setup.py

Generally speaking, use setup.py

to manage code packaging, installation, and deployment issues. The industry standard way of writing is to use Python's popular packaging tool setuptools to manage these things. This approach is commonly used in open source projects. However, the core idea here is not to use standardized tools to solve these problems. Instead,

a project must have an installation and deployment tool, which can quickly and easily install the environment and code on a new machine. Deploy and run the program.

I have been through this trap before.

When I first started writing projects in Python, the process of installing the environment, deploying the code, and running the program was all done manually. I encountered the following problems:

　1. When installing the environment, I often forget to add a new Python package recently. As a result, the program will go wrong as soon as I run it online;

　2. The version dependency problem of Python packages. Sometimes we use one version of the Python package in our program, but the official package is already the latest package. It may be installed incorrectly through manual installation;

　3. If there are many dependent packages, it is very time-consuming to install these dependencies one by one;

　4. When new students start writing projects, it is very troublesome to run the program. , because you may often forget how to install various dependencies.

　setup.pyYou can automate these things to improve efficiency and reduce the probability of errors. "Automate complex things, and things that can be automated must be automated." This is a very good habit. The documentation of setuptools is relatively large. If you are new to it, it may not be easy to find the entry point. The way to learn technology is to see how others use it. You can refer to a web framework in Python and how flask is written: setup.py.

Of course, it is not a bad idea to simply write your own installation script (deploy.sh) instead of setup.py.

requirements.txt

## The purpose of this file is:

　1. Convenient for developers to maintain software package dependencies. Add new packages during the development process to this list to avoid missing software packages when installing dependencies in setup.py;

　2. Convenient for readers to clarify Which Python packages are used in the project.

The format of this file is that each line contains a package dependency description, usually in the format of flask>=0.10. The requirement is that this format can be pipIdentification, so that all Python package dependencies can be installed simply through pip install -r requirements.txt. Specific format instructions: Click here.

About how to use the configuration file

Note that in the above directory structure, conf.py is not included Place it in the source code directory, but in the docs/ directory:

Many projects use the configuration file as follows:

1. The configuration file is written in one or more python files, such as conf.py here;

2. Which module in the project uses this configuration file Just use the configuration in the code directly through import conf.

I don’t agree with this approach:

1. This makes unit testing difficult (because the module relies on external configuration) ;

　2. On the other hand, the configuration file serves as the interface for the user to control the program, and the user should be able to freely specify the path of the file;

3. The reusability of program components is too poor, because this hard-coded code runs through all modules, making most modules dependent on the conf.py file;

Therefore, I think the better way to use configuration is:

1. Module configurations can be flexibly configured and are not affected by external configuration files;

　2. The configuration of the program can also be flexibly controlled.

What can support this idea is that students who have used nginx and mysql know that nginx and mysql programs can freely specify user configurations.

Therefore, the configuration file should not be used directly import conf in the code. conf.py in the directory structure above is a configuration example, not a hard-coded configuration file that is directly referenced in the program. You can let the program read the configuration content by specifying the configuration path for the main.py startup parameter. Of course, you can change the conf.py here to a similar name, such as settings.py. Or you can also use content in other formats to write configuration files, such as settings.yaml and the like.

In the module, the calling problem of different files can only be realized under the directory of the same level. If they are in modules of different levels, environment variables must be configured so that the programs can be run at the same level. under the directory structure.

The steps to configure environment variables are as follows:

　'''Configure environment variables, because they are in different directories To import, you must first configure the environment variables so that the programs can call each other in the same directory state'''
　import sys,os
　''os .path.abspath is the absolute path to the file'''
Data = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__) )))
　print(data)
　sys.path.append(data)

First, import the modules sys, os, __file__ is to get the file name of the current file; os.path.abspath() is to get the absolute path of the current file; os.path.dirname() It is to obtain the upper-level path of the current file path; sys.path.append() is to add the current file path to the file path to realize the configuration of the file path and realize the call in the same level.

　

The above is the complete file type of an App. Different functional modules are stored in different files. The App has a program master. Entry, in fact, when we call the main entrance, the environment variable is the location of the main entrance of the program. In the future, you need to write code in a standardized way and try to call between different modules; let’s look at a simple web framework type:

First, the above is a DJ framework:

　--backend front-end, used to store database verification modules and logic modules;

　--config file configuration module, used to store file configuration information;

　--frontend is the front end;

　--user_main.py is the main entrance of the program and the execution module of the program.

The above is the detailed content of Why should we design a good directory structure?. For more information, please follow other related articles on the PHP Chinese website!