- Соглашение о структуре проекта
- (NEW) Соглашения о Git //В работе
- Соглашение об именовании
- Соглашение о БД
- Соглашение об очередях
- Соглашение о логировании
- (NEW) Соглашения об исключения //В работе
- Рекомендации по написанию скриптов
- (NEW) Рекомендации о тестировании //В работе
Стандарт скрипта необходим для поддержания удобочитаемости скрипта, согласованности и совместной работы в команде разработчиков. Скрипт, который соответствует отраслевым методикам и установленным рекомендациям, проще понимать, поддерживать и расширять. Большинство проектов применяют согласованный стиль с помощью соглашений о скрипте
Разделение проекта на слои
Разбиение этого проекта на несколько слоев на основе обязанностей позволяет повысить удобство поддержки проекта├───Common (слой шаблонов и прочих файлов)
├───Helpers (слой независимых функций)
├───Infrastructure (слой работы с сервисами/интеграциями)
│ ├───DataBase (работа с бд)
│ ├───Mail (работа с почтой)
│ └───PIX Master API (работа с API мастера)
├───States (слой состояний)
│ ├───Init
│ │ └───Transactions
│ ├───GetSetTransaction
│ │ └───Transactions
│ ├───Process
│ │ └───Transactions
│ └───EndProcess
└───Tests (слой тестов)
├───IntegrationTests
└───UnitTestsИспользуйте PascalCasing
Используйте регистр pascal (”PascalCasing”) и префиксы in, out, io при именовании параметров скриптаИспользуйте camelCasing
Используйте регистр camel (”camelCasing”) при именовании переменных в скриптах
Не игнорирейте конвенции нейминга языка или компании
Мы должны знать общие правила нейминга в компании и своего языка программирования. Наш код должен быть достаточно близок к индустрии, из которой будут приходить люди, чтобы его поддерживать и развивать. В то же время в компании может быть своя прослойка правил, чтобы поддержка большой кодовой базы была проще и инженеры могли легко переключаться между проектами.
Наименование должно отражать значение
Переменная — это какие-то данные, какое-то значение, но не стоит её так и называть. Конкретизируйте. Что за значение мы хотим в ней хранить? Так и назовём переменную.
Не используйте несколько вариантов для одного термина
Можно встретить варианты нейминга одних и тех же терминов, поэтому лучше обговаривать найминг или вести глоссарий
Примеры:
Поставщик: provider, supplier, vendor, contractor -> suplier
Заказчик: customer, client, consumer -> customer
Цена: price, rate, cost, pricing, worth -> price
Объем: volume, amount, size, bulk, quantity -> volume
Склад: warehouse, storage, store, storehouse -> storehouse
Не используйте кириллицу
В языках программирования принятно писать используя ASCII Characters, используя кириллицу появятся недопонимание со стороны других разработчиков и есть риск появления ошибок кодировки
Не используйте венгерских обозначений
Венгерская нотация повторяет тип, который уже присутствует в объявлении. Это бессмысленно, поскольку PIX Studio идентифицируют тип.
Не используйте избыточных названий
В название добавляется тип переменной или избыточный префикс названия объекта. В итоге мы читаем код как «добавлено дата время» или «корзина — айди корзины».
Не используйте названия без контекста
Только благодаря значениям мы поняли, что за source имеется в виду, в каком смысле употреблены state, status. Без значений всё усложняется — придётся отвлекаться и уточнять, о чём идёт речь.
Не используйте абстрактные названия
По названию свойств сложно догадаться, о чём идёт речь. Почему бы не назвать свойства именем метрики, которую они несут? Не нужно придумывать лишние обозначения, которые не применяются в реальной жизни.
Например: переменная checkAttachments - абстрактное название, если дословно переводить получится "проверка вложений", из названия не понятно что переменная возвращает при наличие или отсутствие вложений. Лучше назвать isWithAttachments или isAttchaments, и нам сразу будет понятно что при наличии вложений будет возвращать true
Избегайте отрицательных переменных
Отрицательные переменные сложные в понимании, а если в коде есть не отрицательные переменные, то легко запутаться
Используйте Bulk запросы
При записи больших таблиц используйте bulk запросы, вместо циклов
- достаточно одного запроса в БД
- быстреее чем простые запросы
| Кол-во записей | Обычный запрос (Insert) | Bulk-запрос (bulk insert) |
|---|---|---|
| 100 | 2 мс | 1,9 мс |
| 1 000 | 18 мс | 8 мс |
| 10 000 | 203 мс | 76 мс |
| 100 000 | 2,13 с | 742 мс |
| 1 000 000 | 21,56 с | 8,3 с |
Тестовая таблица содержит 6 столбцов (Guid, string x2, int, decimal?, DateTime).
Тест проводился локально по конфигурации:
- CPU INTEL i7-10510U с частотой 2,30 ГГц
- RAM DDR3 16 ГБ
- SSD SAMSUNG 512 ГБ
Выборку данных реализуйте в SQL запросах, а не в активностях
- уменьшает потребление памяти (не надо тянуть всю таблицу в оперативку)
- увеличивает производительность
Избегайте создание хранимок в БД
- уменьшает кол-во зависимостей (не надо поддерживать хранимки)
- увеличивает гибкость настройки робота
- упрощает поддержку скриптов
Учитывайте различия между NULL и пустой строкой
При работе с БД, учитывайте различия между null и '', если значения нет то указывайте null. Но если значение должно быть пустое (например результат распознавания вернул пустую строку) то в БД пишем ''- Элементы очереди обновляйте в последнею очередь
- Логируйте прогресс обработки больших данных в % или 0/100
- Логируйте все вложенные ошибки, но избегайте логирование всего трейса исключений в транзакции
- Логируйте исключения добавляя данные об транзакции (не конфиденциальные)
- Избегайте логирование конфиденциальной информации
- Избегайте логирование начало/конца скрипта
Соблюдайте соглашение о коде C#
Стандарт кода необходим для поддержания удобочитаемости кода, согласованности и совместной работы в команде разработчиков. Код, который соответствует отраслевым методикам и установленным рекомендациям, проще понимать, поддерживать и расширять. Большинство проектов применяют согласованный стиль с помощью соглашений о коде. И dotnet/docsdotnet/samples проекты не являются исключением. В этой серии статей вы узнаете о наших соглашениях по программированию и средствах, которые мы используем для их применения. Вы можете принять наши соглашения как есть или изменить их в соответствии с потребностями вашей команды.
Соблюдайте SRP (SOLID)
SRP – принцип единой ответственности. Этот принцип означает, что каждый скрипт в вашем коде должен выполнять одну операцию.
Соблюдайте принцип DRY
DRY – Don’t repeat yourself (не повторяй себя). Всегда думайте о том, как можно переиспользовать тот или иной фрагмент скрипта. Что можно выделить в универсальный скрипт/функцию. Речь не идет о написании активностей - я имею в виду очень похожею логику, которая встречается в нескольких местах.
Есть еще принипы KISS, YAGNI:
KISS - Keep it simple, stupid («Сделай это проще, тупица») - "чем проще - тем лучше", но это не означает сделать быстро и кое как
YAGNI - "тебе это не нужно", не прописывай функции, которые могут и не понадобиться в будущем
Используйте минимальное кол-во аргументов
- Меньше - лучше
- Если скрипт принимает слишком много аргументов, возможно он нарушает SRP
- Большое кол-во аргументов - проблемы с тестированием
- Большое кол-во аргументов возможно стоит завернуть в объект(например словарь)
Используйте $,@,""" при работе со строками
Используйте LINQ
Используйте LINQ вместо циклов и встроенных активностей при работе с коллекциями
Плюсы
- Компактный, умещается в одну активность
- Упрощает понимание запроса/алгоритма
- Гибкий, расширяемость и деревья выражений позволяют выполнить любой запрос
- Наличие методы для паралельной обработки
Минусы
- Сложная отладка больших запросов
- Производительность (for > foreach > LINQ)
Примеры:
Исключения:
- При работе с внешними сервисами (файлы, почта, БД,UI)
- Большая бизнес логика
Используйте условные операторы
Использование условных операторов вместо встроенных if активностей, позволяют писать компактные и легко читаемый код
Операторы с условным ?. значением NULL и ?[]
Тернарный условный оператор (?: оператор)
в PIX контекстные значения, это свойства в C#, поэтому нельзя использовать out и ref напрямую
Операторы объединения со значением NULL (?? И?? = операторы)
Исключения:
- Большая бизнес-логика
Избегайте Boxing и Unboxing
По сравнению с простыми операциями присваивания операции упаковки и распаковки являются весьма затратными процессами с точки зрения вычислений. При выполнении упаковки типа значения необходимо создать и разместить новый объект. Объем вычислений при выполнении операции распаковки, хотя и в меньшей степени, но тоже весьма значителен.
Избегайте комментариев
Комментарии не нужны, пишите самодокументируемый код. Если комментарии необходимы, стоит задуматься об чистоте кода
Исключения:
- TODO
- Поведения, противоречащее логике
Избегайте флагов в аргументах
Флаг указывает на то, что у метода есть несколько функций. Лучше всего, если у метода есть только одна функция (принцип SRP). Разделите метод на две части, если логический параметр добавляет к методу несколько функций.- упрощает поддержку
- упрощает модульное тестирование
Например вместо CreateFile → CreateFile, CreateTempFile
Избегайте глубоких вложенний
ДобавитьИзбегайте отрицательных условий
ДобавитьИзбегайте громоздких if-ов
ДобавитьВременные решения
- Если скрипт часто вызывается, замените его на контейнер (пока не решится вопрос логами)
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent