Соблюдение порядка в проекте в процессе сопровождения сайта

Введение

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

С каждой новой правкой проект усложняется и при беспорядочном способе организации кода. В итоге в проекте будет все сложнее понять что где находится. 

Здесь приведены советы, как  с этим бороться. 

Хранимые процедуры 

Выделять выходные SELECT комментацием -- SELECT 1

Так будет проще понять, что выдается на выход наша процедура и сложнее перепутать выходные select с присвоением  переменных через SELECT.

Выносить типовые операции в отдельные функции или процедуры

Типовые действия необходимо прописывать один раз в некой функции и процедуре, и затем вызывать ее там, где требуется. 

Примеры для функций - проверки доступа, вывод дат или метрик (форматирование вывода). 

Примеры для процедур - создание заказа, логирование каких-то операций.

Если этого не делать, то у вас будет в итоге много дублирующего кода. К примеру, создание заказа может в будущем проходить по API и лучше и на форме и  в методе API использовать 1 хранимую процедуру (например, srv_createOrder). 

Если чувствуете, что параметров у процедуры может быть в будущем больше, то проще в нее передавать @parameters ExtendedDictionaryParameter. 

Псевдонимы для таблиц в JOIN

В SELECT запросы, если идет JOIN, то всегда используйте псевдонимы для таблиц и поля используйте с псевдонимами.

Это нужно чтобы безопасно можно было добавлять потом поля в таблицу БД.

К примеру у заказа есть поле ord и идет JOIN с категориями. И мы заказы вывели на таблице. В будущем, если кто-то добавит ord у категорий, то запрос SELECT упадет (т.к. поле ord есть у обоих таблиц). Поэтому сразу прописывайте в JOIN псевдонимы таблицы (например, prod и cat) + обращаемся к полем через и эти имена (select prod.ord...).

Писать только с соблюдением шаблона для процедур компонентов 

У каждого компонента процедуры имеют свою структуру. Лучше минимально отходить от шаблона процедур - в этом случае их проще читать и понимать, проще поддерживать. 

Всегда придерживаться 1 нотации в проекте (какая уже есть в проекте). 

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

В идеале добиться, чтобы нельзя по стилю именования было понять кто создавал объекты.

Чем все более типовое для проекта - тем проще это понимать в будущем. 

Периодические действия

Не нужно писать большие портянки в процедурах day, hour и т.д.

Выносите их в отдельные процедуры с понятным названием - тогда код процедур day, hour будет компактным. 

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

Дополнительные стили CSS и скрипты JS

Избегайте помойки в глобальных CSS, JS

Стили, скрипты для 1 страницы лучше размещать не в глобальным CommonStyles, CommonScripts, а прямо на этой странице.

Не нужно засорять глобальные JS и CSS моментами, которые относятся к 1-2 страницам (как вариант, можно вынести в отдельный файл css или JS и его подключить к нужным страницам). 

Минимизация кастом стилей и скриптов

Попробуйте обойтись без кастом стилей (используя стандартные классы Bootstrap) и JS-коллбеки размещать у формы в отдельном специальном поле. 

В отдельных случаях можно обойтись и без JS через использование Actions и RefreshContainer. 

Чем больше кастом CSS и JS, тем сложнее будет поддержка проекта, и тем больше в нем будет нестабильности, нюансов и т.д. 

Если идет совсем жесткий кастом системных элементов или глобальных элементов на страницах, то есть риск, что это может в будущем конфликтовать с обновлением ядра. Лучше минимально трогать системные элементы платформы. 

Таблицы базы данных

Структура таблиц может только расширяться, а не меняться

Исходите из принципа, что можно только наращивать струткуру БД, а не менять ее по ходу эксплуатации. 

Не меняйте типы существующих полей и не удаляйте поля. 

Если вы удаляете поле, то это может сказаться на каких-то существующих запросах в системе (и это может выясниться не сразу). 

Сразу учитывайте возможное расширение функциональности

Чем лучше вы предскажете дальнейшее развитие системы, тем меньше вам  надо будет переделывать по структуре БД и ниже риски нестабильности.

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

Также тип полей таблиц указывайте с учетом возможных пожеланий по расширению. 

Пример: Если у задач хотят внедрить приоритет, то возможно сразу имеет есть сделать числом а не bit, т.к. приоритетнось может быть несколько уровней.

Используйте стандартные имена именования колонок

Чем более стандартные имена, тем проще писать SQL код. Имена должны быть ожидаемые. Разработчик не должен постоянно проверять, как называются поля в таблице. 

Примеры стандартных имен:

• name (название),
• description (описание),
• ord (порядок для сортировки),
• color (цвет),
• statusID (статус объекта), 
• parentID (ссылка на родителя), 
• code (кодовое название), 
• isDisabled (заблочено),
• created(когда создал),
• createdBy (кто создал). 

Чем меньше вычурных имен и неожиданных моментов - тем проще будет это использовать и поддеживать.

Не нужно в имени дублировать сущность (например, вместо name использовать productName). Также не нужно указывать на тип (венгерская нотация) - strName. 

Без фокусов в плане ключей

Не нужно экспериментировать на рабочем сайте с ключами.

У таблицы ставим всегда id primary key identity (1,1). 

Внешние ключи делаем всегда int и наименование вида categoryID (т.е. это ссылка на категорию). 

Много-ко-многим делаем через отдельную таблицу, где 2 внешних ключа на другие таблицы (например, productID, categoryID в таблице as_cat_productCategories).

Отклоняться от этих правил стоит только в угоду оптимизации большой таблицы (например, guid в качестве primary key). 

Папка /uploads 

Не засорять корень папки большим кол-вом файлов

В корне лежат несколько важных файлов, и лучше их не смешивать с множеством других файлов.

Создавайте папки и в них помещайте необходимые файлы. 

Удалять временные файлы после операций

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

ВАЖНО. Не делайте сложные выборки для удаления, чтобы не удалить ничего лишнего по ошибке. Логика удаления должна быть максимально простой, чтобы уменьшить риск потери ценных данных из-за логической ошибке в коде.

См. также - Заметки по ревизии кода, как улучшить свой код