> For the complete documentation index, see [llms.txt](https://um-dzm.gitbook.io/um_dzm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://um-dzm.gitbook.io/um_dzm/gaid.md).

# Гайд

## Оглавление

1. [**Трекер**](#treker)
2. [**Фазы работы над задачей**](#fazy-raboty-nad-zadachei)
3. [**Структура ноутбука**](#struktura-noutbuka)
4. [**Оформление ноутбука**](#oformlenie-noutbuka)
5. [**Гит**](#git)
6. [**Вывод**](#vyvod)

### Трекер

* **Любую задачу оформляем в трекере**. Если это не сделал внутренний заказчик/руководитель — делайте это самостоятельно.
* В репозитории tasks **создаём папку**, названием которой является номер задачи из трекера. В этой папке создаём файл, называем так:

```
<номер> <название задачи>.ipynb
```

* Если задача подразумевает несколько ноутбуков, то они создаются с разными **осмысленными названиями** в той же папке
* Ноутбуки в одной папке с номером задачи должны быть **объединены одной идеей и одной глобальной задачей**. Если нужно что-то протестировать или попробовать без создания задачи — создавайте файл вне папок с тасками, например в своей папке
* Если при получении задачи вы видите, что она похожа на одну из предыдущих, очень желательно **найти её и добавить в связь в трекере**. Решить такую задачу можно в старой задаче, но создав новый ноутбук (в трекере в комментах укажите, что решение находится в другой таске)

### Фазы работы над задачей

* **Получение задачи**. Убедиться, что задача ясна, все формулировки и термины в ней понятны.
* **Наличие данных**. Убедиться, что все данные у нас есть. При необходимости запросить дополнительно, либо предупредить заказчика об ограничениях и найти компромисс.
* **Решение**. Приступать к решению тогда, когда вам все понятно в ТЗ и вы уверены, что сможете предоставить требуемые данные.
* **Проверка результата**. Проверьте корректность результата. Обратите внимание на типы данных, NULL значения и тп.
* **Предоставление заказчику**. Будьте внимательны с отправкой персональных данных "наружу", это лучше уточнять.
* **Внесение правок** по обратной связи от заказчика.

### Структура ноутбука

1. Все **импорты** — в первой ячейке
2. Обязательно создавайте **объект класса TaskEnvironment с номером задачи**:

```python
te = g.TaskEnvironment('<номер> <название задачи>')
```

3. Далее ячейки (от 1 до нескольких) **для объявления констант**. Константы обозначайте прописными буквами.&#x20;
4. Затем, при необходимости, идут **блоки определения функций**. Используйте **аннотации типов** для аргументов и возвращаемого значения. Они не обязаны быть строгими, так как мы не используем статические валидаторы, например, как mypy, но другому разработчику должно быть понятно что принимает и возвращает функция.
5. **Получение данных из файлов** и их обработка (если нужно в задаче). Обратите внимание, все файлы должны быть размещены на диске О, например, в папке `te.common_folder`
6. **Решение**
7. **Запись файлов и отправка/рассылка**. Не отправляйте и не записывайте файлы где-то в середине ноутбука, выделяйте их в отдельные блоки в конце задачи.

* Соблюдайте правило, чтобы перезапуск ноутбука "вслепую" **не приводил к нежелательным последствиям** (рассылка, которая не нужна; перезапись нужных файлов и тп)

### Оформление ноутбука

* **Не используйте "магические числа"** в коде. Выносите все в переменные и константы.

```python
# не очень хорошо
sa.literal_column('EVENT_DATE') == '2024-09-01',

# лучше так
CURRENT_RCP_DATE = '2024-09-01' # определяется в первых ячейках, здесь приведено для наглядности
sa.literal_column('EVENT_DATE') == CURRENT_RCP_DATE

# не очень хорошо
sa.literal_column('SERVICE_TYPE').in_(('Гастроскопия','Колоноскопия','УЗИ')),

# лучше так
SERVICE_TYPE_SLICE = (
		'Гастроскопия',
		'Колоноскопия',
		'УЗИ'
		)
sa.literal_column('SERVICE_TYPE').in_(SERVICE_TYPE_SLICE)
```

* **Осмысленный нейминг**. Важно, чтобы можно было вернуться к коду через месяц и понять что в нем происходит. По возможности, используйте наименования, уже широко используемые окружающими вас разработчиками в ноутбуках и gennady.

```python
# плохо
date_1 = '2024-04-01'
priem_date = '2024-04-12'
lst = ['21389672', '30000009566075', '30000014852616', '30000000986105', '21701005']

def db(x):
	return x * 2

# хорошо
rec_date = '2024-04-01'
rcp_date = '2024-04-12'
pats_without_rec_slice = ['21389672', '30000009566075', '30000014852616', '30000000986105', '21701005']

def multiply_by_two(x):
	return x * 2
	

```

* **Соблюдайте форматирование**: следите за отступами, переносами строк, чтобы код был читаемым. Желательно использовать форматтер (предпочтительные: black+isort). В репозитории gennady предпочтительными являются одинарные кавычки и двойные тройные.
* **Удаляйте отладочный код** (особенно тяжёлый) после того, как закончили работу над задачей
* **Логически разделяйте фрагменты задачи** - используйте для этого ячейки Markdown. Переключить тип ячейки на маркдаун можно нажатием клавиши 'M', переключить обратно для кода - 'Y'. В ячейке маркдаун вы можете написать подзаголовок так:

```
# Заголовок 1 уровня
## Заголовок 2 уровня
### Заголовок 3 уровня
```

* **Добавляйте комментарии** для неочевидных моментов. Всегда представляйте, что с вашим кодом завтра будет работать другой человек.

### Гит

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

### Вывод

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