Post #380

Пост по заявкам читателей (да, так тоже можно!) про названия. Тема-то актуальная, регулярно в чатах кто-нибудь спрашивает. Итак, мы проектируем системы и даём названия разным элементам. В основном это: * таблицы в базах данных * поля в таблицах * индексы, ограничения и бизнес-правила * эндпоинты API * поля в JSON * названия файлов Есть ещё, конечно, названия модулей, функций и переменных, но это область программистов, туда не лезем. Что же у нас с рекомендациями? Удивительно, но они разные :) Вот какие вопросы обычно обсуждают. Во-первых, у нас есть разные способы записи названий, состоящих из нескольких слов. Пробелы мы почти никогда использовать не можем, остаются варианты: 👨‍🎓 PascalCase (без пробелов, с большими буквами в начале слов) 🐫 camelCase (без пробелов, с большими буквами в начале слов, начиная со второго, как горбы у верблюда) 🐍snake_case (вместо пробелов используется подчеркивание, всё маленькими буквами) 🍢kebab-case (вместо пробелов используется "минус", слова нанизаны на шампур) Во-вторых, какие части речи использовать — глаголы, существительные? Особенно актуально для эндпоинтов API В-третьих, для существительных — во множественном или в единственном числе их называть? В-четверых, словарь. Какими словами вы называете объекты, и как переводите на английский (надо ли говорить, что называть все объекты нужно на английском, если только у вас не 1С). Как вы назовете счет клиента? Account, Check или Schet? Любопытно, что рекомендации и лучшие практики для API и для БД иногда противоположны! Для БД советуют использовать snake_case (так проще различать слова). Для эндпоинтов API — kebab-case, т.к. в вебе ссылки принято подчеркивать, и значок "_" может потеряться. Почему не camelCase? Потому что труднее различать слова и нужно переключать регистр (URI регистрозависимые). В обоих случаях рекомендуется использовать в качестве названий существительные во множественном числе (для ресурсов REST API и для названий таблиц в БД). Один из аргументов для БД — меньше риск, что имя таблицы совпадет с зарезервированным словом. Хотя есть и контраргумент: давать таблицам и представлениям названия в единственном числе, чтобы не думать, как переводить во множественное (person — это persons или people?). Холиварная тема! Следующая тема — идентификаторы. Должны ли они называться просто id, или повторять название сущности (team_id?) Есть аргументы за и против. Внешние ключи, понятно, должны назваться по названию внешней таблицы+id. Названия таблиц и полей должны содержать полные слова, не сокращения. Нет ничего хуже таблицы pmnt23, состоящей из полей P1, NMT, ABBR14, FIELD28, ACC_NO и т.д. Названия типов также не должны становиться именами полей: DATE, TEXT или TIMESTAMP не дают никакого объяснения смысла. Также стоит подумать над более конкретными названиями — source_warehouse_id а не просто source_id. Для API, кроме того, нужно понимать — запрашиваем ли мы коллекцию или единичный элемент? Если это элемент из коллекции, то будет существительное во множественном числе / id (users/{id}), но это может быть и служебное слово, указывающее на особенный элемент коллекции (users/me). Про глаголы в REST писать не буду, пуристы скажут, что никаких глаголов в названиях эндпоинтов быть не может, но вот Google, например, считает иначе. Ну а если у вас не REST, а наоборот даже RPC, то названия методов рекомендуется писать в PascalCase по формату "ГлаголСуществительное" — что мы делаем и над чем мы это делаем, причем существительное должно указывать на тип передаваемого объекта (GetBook возвращает объект Book). Ну и пока нам не встречался camelCase, куда же без него. Он у нас живет внутри JSON — так записываются названия полей.