Organization and maintenance of large code bases: main library, data, UI, documentation and wiki, tests, legacy components and third-party components...How to track and maintain order of all this content? Organization of files in codebases can be a difficult task.
Don't worry - we can do it! This article will review the most commonly used systems for small and large projects and provide some easy-to-follow best practices.
As with almost all project management-related tasks—documentation, software submission, deployment—you will benefit greatly from a conscious, programmatic approach. This will not only reduce the current problems, but will also save you and your team valuable time when content needs to be quickly accessed and reviewed in the future.
You can definitely recall the function name of anything you are writing right now and quickly find the files you need to edit and clearly tell what works and what doesn't - or what you think so. But, can you say the same thing about the project you worked on last year?Let's admit: software projects may last for months or even years of inactivity. A simple README file can do a lot of things for your colleagues or future you. But let's consider other ways you can build a project and build some basic rules to name files, process project documentation, and to some extent organize an effective workflow that stands the test of time.
Understanding things
We will establish a "baseline" for the documents in an organization project - a logic that will serve us in many situations within the scope of software development.Consistency is the name of the game. Make sure you understand (and discuss or argue) what the rules are and follow them after consensus is reached.
This is a reference list of files that almost every software project should have:
AUTHORS: The attribution of the person involved in writing the code.
Some examples might be:
Internationalization (i18n) and localization (l18n)
We want to restrict the creation of directories to keep things manageable, whether in the root directory (the main components will be located here) or recursively (within each directory). Otherwise, we may end up spending a lot of time routinely browsing files in well-organized directories.
Please exclude these
from the source treeData. You might be tempted to have a data/directory in the source tree for CSV files, etc., especially if they only take up a few kilobytes. But what if they take up megabytes or even gigabytes (which is not uncommon these days)? Do you really want to submit these to your code like you would with your code base? No.
Binary file. You do not want the video rendering or compiled executables to be located next to the source code. These are not development files, they don't belong here at all. Like data files, they may end up taking up a lot of space.
Settings. This is another big taboo. You should not place credentials, passwords, or even security tokens in your code base. We can't cover a solution to this problem here, but if you're a Python developer, consider using Python Decouple.
Let's consider a web application—a software that runs on a web server that you can access through a browser, whether on a desktop or a mobile device. And assuming it is a web application that provides membership to access some kind of premium service—probably exclusive reports, travel tips, or video libraries.
<code>├── .elasticbeanstalk ├── .env ├── billing ├── changelog.txt ├── locale │ ├── en │ └── zh_Hans ├── members ├── readme.txt ├── static │ ├── fonts │ ├── images │ ├── javascript │ └── styles ├── templates │ ├── admin │ └── frontend ├── todo.txt └── tools</code>
This is a basic web application structure with support for two languages (English and Simplified Chinese (locale directory). There are also two main components, billing and members.
If you are a little more familiar with website development, the contents of the static and templates folders may look familiar. Perhaps the only unusual element might be .elasticbeanstalk, which stores deployment files for Amazon Web Services (AWS), and .env, which only stores settings for projects on-premises such as database credentials. The rest, such as README and TODO, we have discussed it. tools directory is an interesting directory. Here we can store scripts, for example, trim the database, check payment status, or render static files to cache—basically, anything that is not the application itself but helps make it work.
Regarding naming, if we name the images directory as images/ or img/, or name the styles directory as styles/ or css/, or name the javascript/ directory as js/, there is no difference. The main thing is that the structure is logical, and we always follow a certain convention, whether it is a long descriptive name or a short one.Case 2: Desktop Application
Let us now consider an application that you can download and install on your computer. And suppose the application requires some input, such as a CSV file, and then render a series of reports.
File structure
<code>├── .gitignore ├── data ├── doc ├── legacy │ ├── dashboard │ ├── img │ └── system ├── LICENSE ├── README ├── tests ├── thirdparty ├── tools │ ├── data_integration │ └── data_scraping ├── ui │ ├── charts │ ├── css │ ├── csv │ ├── dashboard │ ├── img │ │ └── icons │ ├── js │ ├── reports │ └── summaries ├── VERSION └── wiki</code>
legacy/ folder is used for part of the application that is about to be discontinued, but still provides some features that may come in handy until it is completely refactored into a new system. Therefore, it provides a good way to separate the old code from the current code.
A new addition here is tests/, which provides a place to ensure quality using unit tests, and thirdparty/, a place to store external libraries required by the software.
Note that there are doc/ and wiki/ folders, which may look like a duplicate. However, it is also entirely possible to have a document folder for the end user and a wiki for the development team - even reasonable.
The good news worth repeating is: even if you work alone, you must be organized. Hopefully this article provides you with some ideas that you can start applying to your workflow right away to prevent confusion as the number of files in your application increases.
As mentioned earlier, the guidelines may change from time to time, because (almost) every project is different, and so is the team. Ideally, you or your team will decide how to build a project — add a small document to describe the reasons for this structure — and then you will stick to these rules from now on.
Remember that for many of the guidelines here, it doesn't matter if you choose a dash or underscore to name a file (select one of the many topics). The key is consistency.
There are many benefits of organizing project documents in a structured way. First, it improves the readability and maintainability of the code. When files are organized logically, it is easier for developers to understand the code base and make changes without breaking existing functionality. Second, it enhances teamwork. When multiple developers work on the same project, a well-organized file structure ensures that everyone knows where to find a specific snippet. Finally, it speeds up the development process. Developers spend less time searching files and more time writing and optimizing code.
The optimal structure of a project file depends on the nature and complexity of the project. For small projects, a simple directory structure may be enough. However, for larger projects with multiple components, you may need a more complex structure. Consider factors such as the programming language you are using, the framework or library you are using, and the team's preferences. It is important to make the structure flexible so that it can develop as the project grows.
There are several strategies for organizing code. A common method is to group files by function. This means that all files related to a specific function are saved in the same directory. Another way is to group files by type, such as splitting CSS, JavaScript, and HTML files into different directories. Some developers prefer to use a hybrid approach, combining elements of both strategies. The key is to choose a strategy that makes sense for your project and team.
As the code base grows, it is important to check and refactor the file structure regularly. This may include splitting large files into smaller, more manageable files, or reorganizing directories to better reflect the current state of the project. Automation tools can help identify areas in the code base that become clumsy or difficult to maintain. Regular code reviews can also help ensure that new code conforms to the established file structure.
Naming conventions play a crucial role in document organization. Consistent, descriptive file names make it easier to understand what each file contains at a glance. This can greatly speed up the development process, especially when dealing with large projects or working with teams. Naming conventions should be agreed upon at the beginning of the project and always remain consistent.
To ensure that all team members follow your file organization policy, it is important to clearly document your policy and make the document accessible. Regular code reviews can also help enforce the policy. Also, consider using an automation tool that can check if it complies with your document organization rules.
Yes, you can change file organization policies midway through the project, but this should be done with caution to avoid disrupting the workflow. Before making any changes, discuss the proposed new strategy with your team and make sure everyone understands the reasons for the change and how to implement it. It is important to also update any relevant documents to reflect the new policy.
When organizing project files, handling dependencies can be a challenge. One way is to save all dependencies in a separate directory. This makes it easier to manage and update them. Some programming languages and package managers also provide tools for managing dependencies that automate most of the process.
Some common mistakes that should be avoided when organizing project files include: not planning the file structure in advance, not following consistent naming conventions, not recording file organization policies, and irregular checking and refactoring of file structures. Avoiding these errors can help keep the code base neat, organized, and easy to navigate.
There are many resources available to learn best practices for document organization. Online tutorials, coding bootcamps and developer forums can provide valuable insights. Additionally, studying the folder structure of an open source project can provide practical examples of how to effectively organize project files.
The above is the detailed content of How to Properly Organize Files in Your Codebase & Avoid Mayhem. For more information, please follow other related articles on the PHP Chinese website!
Introduction to service providers with cost-effective cloud server prices
File name contains illegal content
Apple mobile phone antivirus
Introduction to standard tags in php
What are the drawing software?
WeChat Moments, two dashes and one dot
How to batch modify file names
How to set Chinese in eclipse
![[Web front-end] Node.js quick start](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
