Создание сайтов в Донецке, ДНР. Как правильно организовать файлы в кодовой базе и избежать хаоса

Основная библиотека, данные, пользовательский интерфейс, документы и вики, тесты, устаревшие и сторонние компоненты... Как мы отслеживаем и поддерживаем порядок во всем этом? Организация файлов в кодовой базе может стать непростой задачей.

Расслабьтесь — у нас есть это! В этой статье мы рассмотрим наиболее распространенные системы как для небольших, так и для крупных проектов, а также приведем несколько простых рекомендаций.

Зачем беспокоиться?

Как и в случае со всеми задачами, связанными с управлением проектами — документацией, фиксацией программного обеспечения, развертыванием — вам будет полезен сознательный программный подход. Это не только сократит количество проблем сейчас, но и сэкономит время вам и вашей команде в будущем, когда вам понадобится быстро получить доступ и просмотреть информацию.

Вы, конечно, можете вспомнить имена функций, которые приходят вам в голову, для всего, что вы сейчас кодируете, и быстро найти файл, который нужно отредактировать, и четко отличить, что работает, а что нет — или вы так думаете. Но не могли бы вы сказать то же самое о том проекте, над которым работали в прошлом году?

Давайте признаем: программные проекты могут бездействовать месяцами и даже годами. Простой файл README может многое сделать для ваших коллег или для себя в будущем. Но давайте подумаем о других способах, которыми вы могли бы структурировать свой проект, и установить некоторые основные правила для именования файлов, работы с проектной документацией и до некоторой степени организовать эффективный рабочий процесс, который выдержал бы испытание временем.

Осмысление вещей

Мы установим «основу» для организации файлов в проекте — логику, которая послужит нам в ряде ситуаций в рамках разработки программного обеспечения.

Как и в случае с нашими правилами для правильного внесения изменений в кодовую базу, ничто из этого не высечено на камне, и, что бы это ни стоило, вы и ваша команда можете придумать разные рекомендации. В любом случае, постоянство — это название игры. Убедитесь, что вы понимаете (и обсуждаете или оспариваете), что такое правила, и следуйте им, как только вы достигли консенсуса.

Обязательный набор

Это справочный список файлов, которые должны быть почти в каждом программном проекте:

README: это то, что GitHub отображает для вас прямо под исходным деревом, и это может помочь объяснить, о чем проект, как организованы файлы и где найти дополнительную информацию.

CHANGELOG: чтобы перечислить, что нового, измененного или прекращенного в каждой версии или ревизии — обычно в обратном хронологическом порядке для удобства (последние изменения сначала).

ЛИЦЕНЗИЯ ДЛЯ КОПИРОВАНИЯ: файл, содержащий полный текст лицензии на программное обеспечение, включая некоторую дополнительную информацию об авторских правах, если это необходимо (например, лицензии третьих лиц).

.gitignore: если вы используете Git (скорее всего, так и есть), это также необходимо, чтобы указать, какие файлы не синхронизировать с репозиторием. (Дополнительную информацию см. в учебнике Jump Start Git по.gitignore и документации, а для некоторых идей взгляните на коллекцию полезных шаблонов.gitignore.)

Актеры второго плана

Некоторые дополнительные файлы, которые вы также можете включить, в зависимости от проекта:

AUTHORS: кредиты тем, кто участвовал в написании кода.

BUGS: известные проблемы и инструкции по сообщениям о недавно обнаруженных ошибках.

CONTRIBUTING/ HACKING: руководство для потенциальных участников, особенно полезное для проектов с открытым исходным кодом.

FAQ: вы уже знаете, что это такое.;)

INSTALL: инструкции о том, как скомпилировать или установить программное обеспечение на разных системах.

NEWS: похож на CHANGELOGфайл, но предназначен для конечных пользователей, а не разработчиков.

THANKS: благодарности.

TODO/ ROADMAP: список запланированных будущих функций.

VERSION/ RELEASE: однострочник, описывающий номер текущей версии или название выпуска.

Папки для компонентов или подсистем

Часто мы сталкиваемся с набором функций, которые можно сгруппировать в одну концепцию.

Вот некоторые примеры:

интернационализация (i18n) и локализация (l18n)

модули аутентификации

сторонние надстройки

инструменты общего назначения и задания cron

пользовательский интерфейс (UI) и графический пользовательский интерфейс (GUI)

Все это можно организовать в один каталог «компонент» или «подсистема» — но не сходите с ума!

Мы хотим ограничить создание каталогов, чтобы все было управляемо, как в корневом каталоге (где будут расположены основные компоненты), так и рекурсивно (внутри каждого каталога). В противном случае мы могли бы потратить много времени на рутинный просмотр файлов в тщательно — и чрезмерно — организованных каталогах.

Оставьте это вне исходного дерева, пожалуйста

Как бы нам ни хотелось, чтобы проект был аккуратным и организованным, есть определенные типы файлов, которые мы хотим полностью исключить из него.

Данные. У вас может возникнуть соблазн создать data/в исходном дереве каталог для CSV-файлов и тому подобного, особенно если они занимают всего несколько килобайт. Но что, если они берут мегабайты или даже гигабайты (что в наши дни не редкость)? Вы действительно хотите зафиксировать это в своей кодовой базе, как если бы это был код? Нет.

Бинарные файлы. Вам не нужны рендеры видео или скомпилированные исполняемые файлы рядом с исходным кодом. Это не файлы разработки, и они здесь просто неуместны. Как и в случае с файлами данных, они также могут занимать много места.

Настройки. Это еще одно большое НЕТ. Вы не должны помещать учетные данные, пароли или даже токены безопасности в свою кодовую базу. Мы не можем здесь описать способы обхода этого, но если вы разработчик Python, рассмотрите возможность использования Python Decouple.

Вариант 1: веб-приложение

Давайте рассмотрим веб-приложение — программное обеспечение, которое работает на веб-сервере и к которому вы можете получить доступ через браузер на настольном компьютере или мобильном устройстве. И допустим, это веб-приложение, которое предлагает членство для доступа к своего рода премиальным услугам — может быть, эксклюзивным отчетам, советам для путешественников или библиотеке видео.

Структура файла

├──.elasticbeanstalk

├──.env

├── billing

├── changelog.txt

├── locale

│ ├── en

│ └── zh_Hans

├── members

├── readme.txt

├── static

│ ├── fonts

│ ├── images

│ ├── javascript

│ └── styles

├── templates

│ ├── admin

│ └── frontend

├── todo.txt

└── tools

Анализ

Это базовая структура веб-приложения с поддержкой двух языков — английского и упрощенного китайского для материкового Китая (localeсправочник). Также два основных компонента, billingи members.

Если вы немного знакомы с разработкой веб-сайтов, содержимое папки staticи templatesможет показаться вам знакомым. Возможно, единственными необычными элементами могут быть.elasticbeanstalk, в котором хранятся файлы развертывания для Amazon Web Services (AWS), и.env, в котором только локально хранятся настройки для проекта, такие как учетные данные базы данных. Остальные, такие как READMEи TODO, мы уже обсудили.

Каталог toolsинтересный. Здесь мы можем хранить скрипты, которые, например, обрезают базу данных, или проверяют статус платежа, или отображают статические файлы в кеш — по сути, все, что не является самим приложением, но помогает ему работать правильно.

Что касается именования, не имеет большого значения, назовем ли мы каталог изображений images/или img/, или каталог стилей, styles/или css/, или javascript/каталог js/. Главное, чтобы структурирование было логичным, и мы всегда придерживаемся какой-то условности, либо длинные описательные имена, либо короткие.

Случай 2: настольное приложение

Теперь давайте рассмотрим приложение, которое вы можете скачать и установить на свой компьютер. Предположим, что приложение получает какие-то данные, например CSV-файлы, а затем представляет серию отчетов.

В этом примере мы позволим исходному дереву немного увеличиться.

Структура файла

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

Анализ

Папка ui/, по сути, является ядром приложения. Имена вложенных папок говорят сами за себя (еще одна хорошая практика). И в отличие от нашего примера с веб-приложением, здесь мы выбрали сокращенные имена (например, jsвместо javascript). Еще раз, что действительно важно, так это то, что мы последовательны в рамках проекта.

Ранее я предлагал оставлять файлы данных вне исходного дерева, но там есть data/папка. Как так? Думайте об этом дереве как о ящике разработчика, которому нужны данные для правильного тестирования приложения. Но эти данные все еще не синхронизированы с репозиторием в соответствии с правилами, установленными в.gitignoreфайле.

Папка legacy/предназначена для части приложения, поддержка которого прекращается, но по-прежнему предоставляет некоторые функции, которые могут пригодиться до тех пор, пока она не будет полностью преобразована в новую систему. Таким образом, это хороший способ отделить старый код от текущего.

Также новыми здесь являются tests/, которые предоставляют место для проверки качества с помощью модульных тестов, и thirdparty/место для хранения внешних библиотек, необходимых программному обеспечению.

Обратите внимание, что есть doc/ и wiki/ папки, которые могут выглядеть как дубликаты. Однако также вполне возможно — и даже разумно — иметь папку с документацией, предназначенную для конечного пользователя, и вики для команды разработчиков.

Заворачивать

Стоит повторить хорошее послание: будьте организованы, даже работая индивидуально. Надеюсь, эта статья дала вам некоторые идеи, которые вы можете начать внедрять в свой рабочий процесс прямо сейчас, чтобы предотвратить беспорядок по мере увеличения количества файлов в вашем приложении.

Как уже упоминалось, рекомендации могут меняться здесь и там, поскольку (почти) каждый проект отличается, как и команды. В идеале вы или ваша команда должны решить, как вы структурируете проект — добавив небольшой документ, описывающий обоснование этой структуры, — и с этого момента вы будете придерживаться этих правил.

И помните, что с большинством рекомендаций здесь не так уж важно, если вы выберете тире или подчеркивание для имени файлов (чтобы выбрать одну тему из многих). Последовательность является ключевым.