git 文件夹上库代码上库_如何正确组织代码库中的文件并避免混乱

git 文件夹上库代码上库

The main library, data, UI, docs and wiki, tests, legacy and third-party components … How do we keep track and maintain order within all of this? Organizing the files in your codebase can become a daunting task.

主要库，数据，UI，文档和Wiki，测试，旧版和第三方组件…我们如何在所有这些方面跟踪和维护顺序？ 在代码库中组织文件可能成为一项艰巨的任务。

Relax — we’ve got this! In this article, we’ll review the most common systems for both small and large projects, with some easy-to-follow best practices.

放松-我们已经做到了！ 在本文中，我们将回顾大型和小型项目的常见系统，并提供一些易于遵循的最佳实践。

何必呢？ (Why Bother?)

As with pretty much all of the tasks related to project management — documentation, software commits, deployment — you’ll benefit from taking a conscious, programmatic approach. Not only it will reduce problems now, but it will also save you and your team quality time in the future when you need to quickly access and review things.

与项目管理相关的几乎所有任务(文档，软件提交，部署)一样，您将受益于采取有意识的编程方法。 它不仅可以减少现在的问题，而且还可以在将来需要快速访问和审阅内容时为您和您的团队节省大量时间 。

You surely can recall function names from the top of your head for whatever is it that you’re coding right now, and quickly find a file you need to edit, and sharply tell what works from what doesn’t — or so you think. But could you say the same about that project you were working on last year?

您肯定可以立即从函数的顶部调出函数名称，无论您现在要编码什么，然后快速找到需要编辑的文件，并从不起作用的地方清晰地告诉您什么起作用，或者您认为如此。 但是您能对去年从事的那个项目说同样的话吗？

Let’s admit it: software projects can go on spans of inactivity that last for months, and even years. A simple README file could do a lot for your colleagues or your future self. But let’s think about the other ways you could structure your project, and establish some basic rules to name files, address project documentation, and to some degree organize an effective workflow that would stand the test of time.

让我们承认： 软件项目可能会持续数月甚至数年的不活动状态 。 一个简单的自述文件可以为您的同事或您将来的自己做很多事情。 但是，让我们考虑一下您可以使用其他方法来构建项目，并建立一些基本规则来命名文件，处理项目文档，并在某种程度上组织有效的工作流程，该工作流程将经受时间的考验。

理解事物 (Making Sense of Things)

We’ll establish a “baseline” for organizing files in a project — a logic that will serve us for a number of situations within the scope of software development.

我们将为组织项目中的文件建立一个“基准”，这种逻辑将在软件开发范围内的许多情况下为我们服务。

As with our rules for committing changes to your codebase the right way, none of this is carved in stone, and for what it’s worth, you and your team might come up with different guidelines. In any case, consistency is the name of the game. Be sure you understand (and discuss or dispute) what the rules are, and follow them once you’ve reached a consensus.

就像我们以正确的方式提交对代码库的更改的规则一样，这些都不是一成不变的，并且就其价值而言，您和您的团队可能会提出不同的准则。 无论如何， 一致性是游戏的名称 。 确保您了解(并讨论或争论)规则是什么，并在达成共识后遵循这些规则。

强制集 (The Mandatory Set)

This is a reference list of files that nearly every software project should have:

这是几乎每个软件项目都应具有的文件参考列表：

• README: this is what GitHub renders for you right under the sourcetree, and it can go a long way to explaining what the project is about, how files are organized, and where to find further information.

  自述 ：这是GitHub上呈现适合你的sourcetree下，它可以很长的路要走 ，以解释该项目是约，文件的组织，以及在哪里可以找到进一步的信息是什么。

• CHANGELOG: to list what’s new, modified or discontinued on every version or revision — normally in a reverse chronological order for convenience (last changes first).

  CHANGELOG ：列出每个版本或修订版的新功能，已修改或已停产的产品-为了方便起见，通常按时间倒序排列(最后更改在前)。

• COPYING LICENSE: a file containing the full text of the license covering the software, including some additional copyright information, if necessary (such as third-party licenses).

  COPYING LICENSE ：包含涵盖该软件的许可证全文的文件，如有必要，还包括一些其他版权信息(例如第三方许可证)。

• .gitignore: assuming you use Git (you most probably do), this will also be a must to tell what files not to sync with the repository. (See Jump Start Git’s primer on .gitignore and the documentation for more info, and have a look at a collection of useful .gitignore templates for some ideas.)

  .gitignore ：假设您使用了Git (您很有可能会这样做)，那么这也必须告诉您哪些文件不与存储库同步。 (有关更多信息，请参见Jump Start Git关于.gitignore的入门和文档 ，并查看一些有用的.gitignore模板的集合，以获取一些想法。)

配角 (Supporting Actors)

Some additional files you might also consider including, depending on the project:

您还可以考虑其他一些文件，具体取决于项目：

• AUTHORS: credits to those participating in writing the code.

  AUTHORS ：感谢参与编写代码的人员。

• BUGS: known issues and instructions on reporting newly found bugs.

  BUGS ：已知问题和说明，报告新发现的漏洞。

• CONTRIBUTING/HACKING: guide for prospective contributors, especially useful for open-source projects.

  CONTRIBUTING / HACKING ：针对潜在贡献者的指南，对开源项目特别有用。

• FAQ: you already know what that is. ;)

  FAQ ：您已经知道那是什么。 ;)

• INSTALL: instructions on how to compile or install the software on different systems.

  INSTALL ：有关如何在不同系统上编译或安装软件的说明。

• NEWS: similar to the CHANGELOG file, but intended for end users, not developers.

  NEWS ：与CHANGELOG文件类似，但供最终用户而非开发人员使用。

• THANKS: acknowledgments.

  THANKS ：致谢。

• TODO/ROADMAP: a listing for planned upcoming features.

  TODO / ROADMAP ：计划中的即将发布功能的列表。

• VERSION/RELEASE: a one-liner describing the current version number or release name.

  VERSION / RELEASE ：描述当前版本号或发行名称的单行代码。

组件或子系统的文件夹 (Folders for Components or Subsystems)

Often we’ll come across a set of functionalities that can be grouped into a single concept.

通常，我们会遇到一组可以归为一个概念的功能。

Some examples could be:

一些示例可能是：

• internationalization (i18n) and localization (l18n)
  国际化(i18n)和本地化(l18n)
• authentication modules
  认证模块
• third-party add-ons
  第三方加载项
• general purpose tools and cron jobs
  通用工具和Cron工作
• user interface (UI) and graphical user interface (GUI)
  用户界面(UI)和图形用户界面(GUI)

All these can be organized into a single “component” or “subsystem” directory — but don’t go crazy!

所有这些都可以组织到单个“组件”或“子系统”目录中，但是请不要发疯！

We want to limit the creation of directories to keep things manageable, both on the root directory (where the main components will be located) and recursively (inside each directory). Otherwise, we might end up spending a lot of time routinely browsing files in carefully — and excessively — organized directories.

我们希望限制目录的创建以使内容易于管理 ，无论是在根目录(将在其中放置主要组件)还是在递归目录(在每个目录内部)中。 否则，我们可能最终会花费大量时间来例行仔细地仔细浏览文件，而这些文件却过于有组织。

离开了这一点的Sourcetree的，请 (Leave that Out of the Sourcetree, Please)

As much as we want the project to be neat and organized, there are certain kinds of files we want to leave entirely out of it.

尽管我们希望项目井井有条，井井有条，但有些类型的文件我们希望完全忽略。

Data. You might be tempted to have a data/ directory in your sourcetree for CSV files and such, especially if they take up just a few kilobytes. But how about if they take megabytes or even gigabytes (which isn’t unusual these days)? Do you really want to commit that to your codebase as if it were code? No.

数据 。 您可能会想在源代码树中有一个CSV文件之类的data/目录，尤其是在它们仅占用几千字节的情况下。 但是，如果它们占用兆字节甚至是千兆字节(这在如今已经不常见了)呢？ 你真的希望提交给你的代码，就好像它是代码？ 没有。

Binary files. You don’t want renders of videos or compiled executable files next to source code. These aren’t development files, and they simply don’t belong here. As with data files, they can also end up using a lot of space.

二进制文件 。 您不希望在源代码旁边渲染视频或编译的可执行文件。 这些不是开发文件，它们根本不属于这里。 与数据文件一样，它们最终也可能占用大量空间。

Settings. This is another big NO. You shouldn’t put credentials, passwords, or even security tokens in your codebase. We can’t cover the ways around this here, but if you’re a Python developer, consider using Python Decouple.

设置 。 这是另一个大问题。 您不应该在代码库中放入凭据，密码甚至安全令牌。 我们无法在此介绍解决方法，但是，如果您是Python开发人员，请考虑使用Python Decouple 。

情况1：Web应用 (Case 1: Web App)

Let’s consider a web application — software that runs on a web server and that you can access through the browser, either on your desktop computer or mobile device. And let’s say this is a web app that offers a membership to access a premium service of sorts — maybe exclusive reports, or travel tips, or a library of videos.

让我们考虑一个Web应用程序 -在Web服务器上运行的软件，您可以通过台式机或移动设备上的浏览器进行访问。 假设这是一个网络应用程序，它提供的成员资格可以访问各种高级服务-也许是独家报告，旅行提示或视频库。

档案结构 (File Structure)

├── .elasticbeanstalk
├── .env
├── billing
├── changelog.txt
├── locale
│   ├── en
│   └── zh_Hans
├── members
├── readme.txt
├── static
│   ├── fonts
│   ├── images
│   ├── javascript
│   └── styles
├── templates
│   ├── admin
│   └── frontend
├── todo.txt
└── tools

分析 (Analysis)

This is a basic structure for a web app with support for two languages — English and simplified Chinese for mainland China (locale directory). Also two main components, billing and members.

这是Web应用程序的基本结构，支持两种语言-中国大陆的英语和简体中文( locale目录)。 还有两个主要组成部分， billing和members 。

If you’re a tiny bit familiar with website development, the contents of the static and templates folder might look familiar to you. Perhaps the only unusual elements might be .elasticbeanstalk, which stores deployment files for Amazon Web Services (AWS), and .env, which only locally stores settings for the project, such as database credentials. The rest, such as README and TODO, we’ve already discussed.

如果您对网站开发有点熟悉，那么static和templates文件夹的内容可能会让您看起来很熟悉。 也许唯一不寻常的元素可能是.elasticbeanstalk (用于存储Amazon Web Services(AWS)的部署文件)和.env (仅在本地存储项目的设置，例如数据库凭据)。 其余的，如README和TODO ，我们已经讨论过了。

The tools directory is an interesting one. Here we can store scripts that, for example, prune the database, or check the status of a payment, or render static files to a cache — essentially, anything that isn’t the app itself but helps to make it function properly.

tools目录是一个有趣的目录。 在这里，我们可以存储脚本，例如，修剪数据库，检查付款状态，或将静态文件呈现到缓存中-本质上，不是应用程序本身而是有助于其正常运行的任何内容。

Regarding naming, it doesn’t make much of a difference if we name the images directory images/ or img/, or the styles directory styles/ or css/, or the javascript/ directory js/. The main thing is that the structuring is logical, and we always follow something of a convention, either long descriptive names, or short ones.

关于命名，如果我们将图像目录命名为images images/或img/ ，或者将样式目录命名为styles/或css/ ，或者将javascript/目录命名为js/ ，则并没有什么区别。 最主要的是结构是合乎逻辑的，并且我们总是遵循某种约定，即长描述性名称或短描述性名称。

情况2：桌面应用 (Case 2: Desktop App)

Now let’s consider an application that you can download and install on your computer. And let’s say the app takes some input, such as CSV files, and presents a series of reports afterward.

现在，让我们考虑一个可以下载并安装在计算机上的应用程序。 假设该应用接受了一些输入(例如CSV文件)，然后显示了一系列报告。

In this examples, we’ll let the sourcetree grow a little larger.

在此示例中，我们将使源代码树变得更大一些。

档案结构 (File Structure)

├── .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

分析 (Analysis)

The ui/ folder is, essentially, the core of the app. The name of the subfolders are pretty much self-descriptive (another good practice). And unlike our web app example, here we’ve opted for shortened names (such as js instead of javascript). Once again, what really matters is that we’re consistent within the project.

ui/文件夹本质上是应用程序的核心。 子文件夹的名称几乎是自我描述的(另一种较好的做法)。 而且与我们的网络应用程序示例不同，在这里我们选择了缩写名(例如js而不是javascript )。 再一次，真正重要的是我们在项目中保持一致。

Earlier, I suggested leaving data files out the sourcetree, and yet there’s a data/ folder in there. How come? Think of this tree as a developer’s box that needs data in order to properly test the app. But that data is still out of the repository synchronization, following the rules set in the .gitignore file.

早些时候，我建议将数据文件保留在源树之外，但其中仍然有一个data/文件夹。 怎么会？ 可以将这棵树视为需要数据以便正确测试应用程序的开发人员的盒子。 但是，按照.gitignore文件中设置的规则，该数据仍不在存储库同步中。

The legacy/ folder is for a part of the app that’s being discontinued but still provides some functionality that might come in handy until it’s fully refactored into the new system. So it provides a good way of separating old from current code.

legacy/文件夹用于已停止使用的应用程序的一部分，但仍提供一些在将其完全重构到新系统中之前可能会派上用场的功能。 因此，它提供了一种将旧代码与当前代码分离的好方法。

Also new here are tests/, which provides a place to do quality assurance with unit tests, and thirdparty/, a place to store external libraries that the software needs.

这里还新增了tests/ ，它提供了使用单元测试进行质量保证的位置，而thirdparty/了存储软件所需的外部库的位置。

Notice there are doc/ and wiki/ folders, which might look like duplication. However, it’s also perfectly possible — and even reasonable — to have a documentation folder intended for the end-user, and a wiki for the development team.

请注意，这里有doc/ 和 wiki/文件夹，看起来像重复的文件夹。 但是，也有可能(甚至是合理的)拥有一个供最终用户使用的文档文件夹，以及一个供开发团队使用的Wiki。

结语 (Wrap Up)

A good message is worth repeating: be organized, even when working individually. Hopefully, this article has given you some ideas that you can start implementing into your workflow right away to prevent mess as the number of files in your app increases.

一个好消息值得重复： 组织起来，即使是单独工作也是如此 。 希望本文为您提供了一些想法，您可以立即开始在工作流中实施这些想法，以防止随着应用程序中文件数量的增加而造成混乱。

As mentioned, the guidelines might change here and there, as (almost) every project is different, and so are teams. Ideally, you or your team will get to decide how you structure the project — adding a little document describing the reasoning for this structure — and you’ll then stay consistent with those rules from now on.

如前所述，准则可能会随处更改，因为(几乎)每个项目都是不同的，团队也是如此。 理想情况下，您或您的团队将决定您如何构建项目-添加一个描述该结构原因的小文档-然后您将与这些规则保持一致。

And remember that, with most of the guidelines here, it isn’t all that important if you choose dashes or underscores to name files (to choose one topic among many). Consistency is key.

请记住，按照此处的大多数指南，如果您选择破折号或下划线来命名文件(在多个主题中选择一个)，则并不是很重要。 一致性是关键 。

进一步阅读 (Further Reading)

• Structuring Your Project, from the The Hitchhiker’s Guide to Python.

  《 The Hitchhiker's Guide to Python》中的“ 构建项目 ”。

• A systematic approach for managing project folder structures, from the UX Collective.

  一种来自UX Collective的用于管理项目文件夹结构的系统方法 。

• Effective Project Management: Traditional, Agile, Extreme, Hybrid

  有效的项目管理：传统，敏捷，极端，混合

翻译自: https://www.sitepoint.com/organize-project-files/

git 文件夹上库代码上库