Привет, хабр! Моя прошлая статья об химии в Python рассказывает о том, как написать простой калькулятор молекулярной массы.
Сегодня мы затронем сторону, отличную от написания кода. Мы займемся оформлением и написанием документации, как правильно делать коммиты и как оформлять код.
Все, что вы увидите в данной статье, будет касаться прочитанных мною материалов и полученного опыта.
В мире разработки программного обеспечения правильное оформление документации играет ключевую роль в обеспечении ясности и понятности проекта. Особенно важным этапом в этом процессе является создание и поддержание README файлов в Git репозиториях. README файлы - это первое, что увидит разработчик, приступая к работе с проектом, и хорошо оформленная документация может значительно упростить процесс взаимодействия с кодом.
В данной статье мы рассмотрим ключевые аспекты оформления документации в Git репозитории, обсудим лучшие методики и практики для создания качественной документации. Независимо от того, являетесь ли вы опытным разработчиком или новичком в области Git, эта статья поможет вам создать четкую, структурированную и информативную документацию для вашего проекта. Погружайтесь в мир оформления документации, улучшайте ваши проекты и делитесь своими идеями с сообществом разработчиков Хабр!
Почему документация тоже важна?
Документация поможет пользователям и разработчикам. Да, если им сильно нужно - они могут и просто скачать или почитать код, но многих отсутствие нормальной документации или хотя-бы нормального README файла отпугивает. Что вы бы выбрали - хорошо заполненный и документированный репозиторий или такой же репозиторий, но без какой либо информации? Я думаю, ответ очевиден.
Да и вам может помочь хорошее оформление кода и документации, если вы вдруг вернетесь к проекту, и не захотите воскликнуть "Что за китайская тарабарщина! Какой идиот это писал? А, это я...".
Как оформить README файл
Я не буду рассказывать, как зарегистрироваться на гитхабе, что это такое и зачем. Эта статья не об этом.
Допустим, вы уже создали свой репозиторий. Главное - это изменить или создать README файл. Но что это такое? README - это файл, обычно в формате txt или md (мы будем использовать md, это markdown, язык разметки), в котором содержится базовая информация о проекте.
Вот пример README из моего репозитория
# Oxygen
Программное обеспечение для инженерных вычислений, научно-естественных наук, математики и алгоритмов <!-- описание репозитория -->
<!--Блок информации о репозитории в бейджах-->
<!--Установка-->
## Установка (Linux)
У вас должны быть установлены [зависимости проекта](https://github.com/OkulusDev/Oxygen#зависимости)
1. Клонирование репозитория
```git clone https://github.com/OkulusDev/Oxygen.git```
2. Переход в директорию Oxygen
```cd Oxygen```
3. Создание виртуального окружения
```python3 -m venv venv```
4. Активация виртуального окружения
```source venv/bin/activate```
5. Установка зависимостей
```pip3 install -r requirements.txt```
6. Запуск скрипта для демонстрации возможностей Oxygen
```python3 oxygen.py --help```
<!--Пользовательская документация-->
## Документация
Пользовательскую документацию можно получить по [этой ссылке](./docs/ru/index.md).
[Релизы программы]: https://github.com/OkulusDev/Oxygen/releases
<!--Поддержка-->
## Поддержка
Если у вас возникли сложности или вопросы по использованию пакета, создайте
[обсуждение](https://github.com/OkulusDev/Oxygen/issues/new/choose) в данном репозитории или напишите на электронную почту <bro.alexeev@inbox.com>.
<!--зависимости-->
## Зависимости
Эта программа зависит от интепретатора Python версии 3.7 или выше, PIP 23.2.1 или выше. Если вы заметили, что он данное ПО можно запустить на версии ниже, или он не работает на какой-либо версии, то напишите в [поддержку](https://github.com/OkulusDev/Oxygen#поддержка)
<!--описание коммитов-->
## Описание коммитов
| Название | Описание |
|----------|-----------------------------------------------------------------|
| build | Сборка проекта или изменения внешних зависимостей |
| sec | Безопасность, уязвимости |
| ci | Настройка CI и работа со скриптами |
| docs | Обновление документации |
| feat | Добавление нового функционала |
| fix | Исправление ошибок |
| perf | Изменения направленные на улучшение производительности |
| refactor | Правки кода без исправления ошибок или добавления новых функций |
| revert | Откат на предыдущие коммиты |
| style | Правки по кодстайлу (табы, отступы, точки, запятые и т.д.) |
| test | Добавление тестов |
В самом вверху, при помощи знака #, что означает заголовок первого уровня, мы обозначаем название программы.
Потом идет краткое описание программы.
Ниже - уже поинтереснее. Там вы видите ссылки на изображения-бейджи, которые оповещают, что за репозиторий, какой здесь используется в основном язык, и т.д и т.п. В самом низу этого блока мы видем ссылку на другое изображение - логотип нашего репозитория, ссылка которого уже локальная, сам логотип хранится в папке docs
Под этими бейджами мы видем инструкцию по установке и запуске репозитория. Желательно, он должен расписан поэтапно.
Дальше мы видем блок с ссылкой на пользовательску документацию и релизы. К этому мы вернемся позже.
Под ссылками на документацию мы ввидем блок поддержки, то есть там информация о контактах разработчика и ссылка на создание issue.
Далее идут зависимости. Там мы должны перечислить, что будет нужно установить пользователю.
И в конце - описание коммитов. Вы можете не вставлять их, но я вставляю. Это таблица, в которой хранятся типы коммитов. О них мы сейчас и поговорим.
Коммиты
Коммиты - это заявки, ссылки на обновление репозитория, грубо говоря. И при создании коммита мы должны указывать сообщение. И этого также много значит.
Название типа коммита | Описание |
build | сборка проекта или внешних зависимостей |
sec | обновления безопасности |
ci | настройка CI и работа со скриптами |
docs | обновление документации |
feat | добавление нового функционала |
fix | исправление ошибок |
perf | изменения, направленные на улучшения производительности |
refactor | правки кода без исправления ошибок или добавления новых функций |
revert | откат на предыдущую версию, предыдущие коммиты |
style | правки по стилю кода |
test | добавление тестов |
По правилам, коммит должен быть в повелительном наклонении, потому что это, как бы указание разработчику, что надо делать
git commit -m "feat: add line output" # en, добавьте вывод строки
git commit -m "feat: добавьте вывод строки" # ruПользовательская документация
Чтобы создать ее, нам нужно в корневом каталоге создать каталог docs, а в нем подкаталог ru (получиться должно так: docs/ru)
Зачем нам создавать подкаталог ru в docs, когда все можно и без нее обойтись? Ответ прост - чтобы энтузиасты могли легко помочь нам с переводом документации на другой язык, просто создав новую подкаталог.
Создаем в docs/ru файл index.md с похожим содержанием:
# Oxygen Docs RU
Пользовательская документация Oxygen на русском
## Оглавление
1. [Введение](./getting-started.md)
1. [Основы химии](./chemistry-basics.md)
## Описание коммитов
| Название | Описание |
|----------|-----------------------------------------------------------------|
| build | Сборка проекта или изменения внешних зависимостей |
| ci | Настройка CI и работа со скриптами |
| sec | Безопасность, уязвимости |
| docs | Обновление документации |
| feat | Добавление нового функционала |
| fix | Исправление ошибок |
| perf | Изменения направленные на улучшение производительности |
| refactor | Правки кода без исправления ошибок или добавления новых функций |
| revert | Откат на предыдущие коммиты |
| style | Правки по кодстайлу (табы, отступы, точки, запятые и т.д.) |
| test | Добавление тестов |
В этом файле мы вставляем заголовок и оглавление, а также на всякий случай описание коммитов
Далее мы просто создаем файлы для оглавления, саму документацию в markdown.
Вот пример файла getting-started.md:
# Oxygen Docs RU
Пользовательская документация Oxygen на русском
### [Оглавление](./index.md)
## Введение
Проект Oxygen представляет собой мощное программное обеспечение, разработанное специально для инженерных вычислений, естественно-научных исследованиях, математики и алгоритмизации. Оно обеспечивает разработчиков инструментами, необходимыми для выполнения высокоточных вычислений и анализа данных.
Oxygen основан на передовых алгоритмах, использующихся в сфере инженерии и естественно-научных исследований. Это позволяет разработчикам решать сложные задачи эффективно и точно.
А вот пример файла chemistry-basics.md
# Oxygen Docs RU
Пользовательская документация Oxygen на русском
### [Оглавление](./index.md)
## Основы химии
1. Что такое относительная атомная масса и молекулярная масса:
Относительная атомная масса (также известная как атомная массовая единица, amu) - это масса атома в единицах массы атома углерода-12. Она используется для измерения массы атомов и молекул.
Относительная молекулярная масса - это сумма относительных атомных масс атомов в молекуле. Она позволяет определить массу молекулы в отношении массы атома углерода-12.
2. Число Авогадро:
Число Авогадро равно приближенно 6.02214076 x 10^23 и представляет собой количество атомов или молекул в одном моле вещества. Это основная константа, используемая для связи массы атомов и молекул с массой вещества в молях.
3. Моли:
Моль - это единица измерения количества вещества. Один моль вещества содержит число Авогадро частиц (около 6.022 x 10^23) атомов, молекул или других элементарных частиц.
4. Металлы и неметаллы:
Металлы - это элементы, обладающие характерными свойствами, такими как отличная теплопроводность, проводимость электричества, металлический блеск и гибкость. Примеры металлов включают железо, медь и алюминий.
Неметаллы - это элементы, обладающие характеристиками, противоположными металлам. Неметаллы обычно плохо проводят тепло и электричество и могут быть хрупкими. Примеры неметаллов включают кислород, азот и серу.
5. Электроны, нейтроны и протоны:
Электроны - это элементарные частицы, обладающие отрицательным электрическим зарядом. Они находятся в орбиталях вокруг ядра атома.
Протоны - это элементарные частицы, обладающие положительным электрическим зарядом, и они находятся в ядре атома.
Нейтроны - это элементарные частицы, не имеющие электрического заряда, и они также находятся в ядре атома.
6. Заряд ядра и энергетические уровни:
Заряд ядра - это сумма зарядов протонов в атомном ядре, который определяет химические свойства элемента.
Энергетические уровни - это уровни энергии, на которых находятся электроны в атоме. Электроны находятся на определенных энергетических уровнях и могут переходить между ними, поглощая или испуская энергию в форме света (спектральных линий).
Ваша документация может быть другая, главное - чтобы она была, и желательно качественная.
Заключение
Документация и оформление репозитория - одни из самых главных задач для разработки хорошего ПО. Я надеюсь вам понравилась эта статья, и вы ее оцените!
Моя прошлая статья об химии в python
С вами был доктор Аргентум, до новых встреч, пока!
UPD: от Tryd0g0lik, генераторы
.gitignore - https://www.toptal.com/developers/gitignore/ - генератор
Git Command - https://gitexplorer.com/ - генератор синтаксиса
README - https://readme.so/ru - генератор
