diff --git a/_includes/sqlstyle.guide.ru.md b/_includes/sqlstyle.guide.ru.md index 6c187b3..1d4992c 100644 --- a/_includes/sqlstyle.guide.ru.md +++ b/_includes/sqlstyle.guide.ru.md @@ -3,19 +3,22 @@ ## Предисловие Вы можете использовать это руководство целиком, [сделать его форк][fork] или -создать своё на его основе. Цель — определить, какой стиль вам подходит больше, -и придерживаться его. Если вы хотите предложить изменение или исправить ошибку, -[откройте Issue][issue] или [создайте Pull Request][pull] на GitHub'е. - -Рекомендации, описанные в этом руководстве, во многом пересекаются с описанными -в книге Джо Селко «[Стиль программирования Джо Селко на SQL][celko-ru]» -(оригинал: [SQL Programming Style][celko]). Это, в частности, найдут полезным -те, кто уже знаком с этой книгой. Тем не менее автор этого руководства в -некоторых аспектах более категоричен, нежели Джо Селко, а в других, напротив, -более гибок. И, конечно, нельзя не отметить, что это руководство значительно -короче и лаконичнее [книги Селко][celko-ru] — здесь вы не встретите ни весёлых -историй из жизни, наглядно объясняющих, как и почему лучше не делать, ни длинных -повествований, мотивирующих на использование той или иной рекомендации. +создать своё на его основе. Цель — определить, какой стиль вам подходит +больше, и придерживаться его. Если вы хотите предложить изменение или +исправить ошибку, [откройте Issue][issue] или [создайте Pull Request][pull] на +GitHub'е. + +Рекомендации, описанные в этом руководстве, во многом пересекаются с +описанными в книге Джо Селко +«[Стиль программирования Джо Селко на SQL][celko-ru]» (оригинал: +[SQL Programming Style][celko]). Это, в частности, найдут полезным те, кто уже +знаком с этой книгой. Тем не менее автор этого руководства в некоторых +аспектах более категоричен, нежели Джо Селко, а в других, напротив, более +гибок. И, конечно, нельзя не отметить, что это руководство значительно короче +и лаконичнее [книги Селко][celko-ru] — здесь вы не встретите ни весёлых +историй из жизни, наглядно объясняющих, как и почему лучше не делать, ни +длинных повествований, мотивирующих на использование той или иной +рекомендации. Руководство написано в [формате Markdown][dl-md], что позволяет легко включить его в проект или просто сослаться на него оттуда, что гораздо удобнее, нежели @@ -36,17 +39,18 @@ `YYYY-MM-DD HH:MM:SS.SSSSS`. * **Функции SQL**. Стандартные вместо специфичных (определяемых поставщиком) с целью лучшей переносимости. -* **Код**. Лаконичный и без излишеств, как например: ненужные кавычки или скобки - или неуместное использование оператора `WHERE`. +* **Код**. Лаконичный и без излишеств, как например: ненужные кавычки или + скобки или неуместное использование оператора `WHERE`. * **Комментарии**. Предпочтительно в [стиле C][c-style-comments-ru] — `/*` - (начало) и `*/` (конец). Либо `--` перед комментарием, тогда окончанием будет - новая строка. + (начало) и `*/` (конец). Либо `--` перед комментарием, тогда окончанием + будет новая строка. ```sql SELECT file_hash -- stored ssdeep hash FROM file_system WHERE file_name = '.vimrc'; ``` + ```sql /* Updating the file record after writing to the file */ UPDATE file_system @@ -58,8 +62,8 @@ UPDATE file_system ### Плохой стиль * **CamelCase**. Неудобочитаем. -* **Префиксы и [венгерская нотация][hungarian-notation-ru]**. Префиксы наподобие - `sp_` или `tbl_` избыточны. +* **Префиксы и [венгерская нотация][hungarian-notation-ru]**. Префиксы + наподобие `sp_` или `tbl_` избыточны. * **Множественное число**. Лучше использовать более естественно звучащие собирательные понятия. Например, `staff` вместо `employees` или `people` вместо `individuals`. @@ -74,16 +78,16 @@ UPDATE file_system ### Общее * **Убедитесь** в том, что имя уникально и его нет в -[списке зарезервированных ключевых слов][reserved-keywords]. + [списке зарезервированных ключевых слов][reserved-keywords]. * **Ограничивайте** длину имени 30 байтами (это 30 символов, если не - используется многобайтовый набор символов). + используется многобайтный набор символов). * **Начинайте** имена с буквы и **не заканчивайте** их символом подчёркивания. * **Используйте** в именах только буквы, цифры и символ подчёркивания. * **Избегайте** нескольких подряд идущих символов подчёркивания. * **Используйте** символ подчёркивания там, где вы бы поставили пробел в реальной жизни (например, `first name` станет `first_name`). -* **Избегайте** сокращений. Если их всё же нужно использовать, убедитесь в том, - что они общепонятны. +* **Избегайте** сокращений. Если их всё же нужно использовать, убедитесь в + том, что они общепонятны. ```sql SELECT first_name @@ -109,13 +113,13 @@ SELECT first_name * По возможности **не используйте** `id` в качестве первичного идентификатора таблицы. * **Не создавайте** в таблице столбцов с таким же названием, как у неё самой. -* Названия **всегда пишите** со строчной буквы. Могут быть исключения, например - использование имени собственного. +* Названия **всегда пишите** со строчной буквы. Могут быть исключения, + например использование имени собственного. ### Псевдонимы/корреляции -* **Должны** так или иначе быть связаны с объектами или выражениями, псевдонимом - которых они являются. +* **Должны** так или иначе быть связаны с объектами или выражениями, + псевдонимом которых они являются. * Имя корреляции **обычно составляется** из первых букв каждого слова в имени объекта. * **Добавьте** цифру к имени, если такое уже существует. @@ -129,6 +133,7 @@ SELECT first_name AS fn JOIN students AS s2 ON s2.mentor_id = s1.staff_num; ``` + ```sql SELECT SUM(s.monitor_tally) AS monitor_total FROM staff AS s; @@ -160,15 +165,15 @@ SELECT SUM(s.monitor_tally) AS monitor_total ### Зарезервированные слова -[Зареервированные ключевые слова][reserved-keywords] всегда пишите прописными +[Зарезервированные ключевые слова][reserved-keywords] всегда пишите прописными буквами, например `SELECT`, `WHERE`. -Не испольуйте сокращённый вариант ключевого слова, если имеется полный. +Не используйте сокращённый вариант ключевого слова, если имеется полный. Например, используйте `ABSOLUTE` вместо `ABS`. -Не испольуйте специфичные для какого-либо поставщика СУБД ключевые слова, если в -ANSI SQL есть ключевые слова, выполняющие такие же функции. Это сделает ваш код -более переносимым. +Не используйте специфичные для какого-либо поставщика СУБД ключевые слова, +если в ANSI SQL есть ключевые слова, выполняющие такие же функции. Это сделает +ваш код более переносимым. ```sql SELECT model_num @@ -183,10 +188,10 @@ SELECT model_num #### Пробелы -Можно и нужно использовать пробелы для выравнивания основных ключевых слов по их -правому краю. В типографике получающиеся таким образом «[коридоры][rivers-ru]» -стараются избегать, в то же время в нашем случае они, напротив, помогают лучше -вычленять важные ключевые слова. +Можно и нужно использовать пробелы для выравнивания основных ключевых слов по +их правому краю. В типографике получающиеся таким образом +«[коридоры][rivers-ru]» стараются избегать, в то же время в нашем случае они, +напротив, помогают лучше вычленять важные ключевые слова. ```sql (SELECT f.species_name, @@ -285,8 +290,8 @@ SELECT r.last_name Подзапросы тоже должны быть выровнены по правому краю «коридора», а внутри них самих применяются те же правила форматирования, что и в любом другом запросе. -Если используются вложенные подзапросы, может иметь смысл поставить закрывающую -скобку на новой строке ровно под парной ей открывающей скобкой. +Если используются вложенные подзапросы, может иметь смысл поставить +закрывающую скобку на новой строке ровно под парной ей открывающей скобкой. ```sql SELECT r.last_name, @@ -307,8 +312,8 @@ SELECT r.last_name, * **Используйте** `BETWEEN`, где возможно, вместо нагромождения условий `AND`. * Таким же образом старайтесь **использовать** `IN()` вместо `OR`. * **Используйте** `CASE`, если значение должно быть интерпретировано до - окончания выполнения запроса. С помощью `CASE` можно также формировать сложные - логические структуры. + окончания выполнения запроса. С помощью `CASE` можно также формировать + сложные логические структуры. * По возможности **избегайте** использования `UNION` и временных таблиц. ```sql @@ -332,20 +337,20 @@ SELECT CASE postcode ### Типы данных * По возможности **не используйте** специфичные для той или иной СУБД типы - данных. Это может негативно сказаться на переносимости, а также этих типов может - не оказаться в старых версиях этих же СУБД. + данных. Это может негативно сказаться на переносимости, а также этих типов + может не оказаться в старых версиях этих же СУБД. * Для работы с плавающей точкой **используйте** только `REAL` или `FLOAT`, но - где нет необходимости в подобных вычислениях, всегда **используйте** `NUMERIC` - и `DECIMAL`. Ошибки округления в операциях с плавающей точкой могут оказаться - очень некстати. + где нет необходимости в подобных вычислениях, всегда **используйте** + `NUMERIC` и `DECIMAL`. Ошибки округления в операциях с плавающей точкой + могут оказаться очень некстати. ### Значения по умолчанию * Значение по умолчанию всегда должно **совпадать** по типу со столбцом. Если, скажем, столбец объявлен как `DECIMAL`, не нужно в качестве умолчания указывать значение типа `INTEGER`. -* Значения по умолчанию должны располагаться **после** объявления типа столбца и - **перед** пометкой `NOT NULL`. +* Значения по умолчанию должны располагаться **после** объявления типа столбца + и **перед** пометкой `NOT NULL`. ### Ограничения и ключи @@ -360,15 +365,16 @@ SELECT CASE postcode целостность данных. 1. Ключ должен быть в какой-то степени уникальным. -2. Должна быть согласованность по типу данных для значения во всей схеме, а +1. Должна быть согласованность по типу данных для значения во всей схеме, а также чем ниже вероятность того, что это изменится в будущем, тем лучше. -3. Можно ли проверить значение на соответствие стандарту (например, ISO)? -4. Ключ должен быть как можно проще, чтобы можно было без трудностей +1. Можно ли проверить значение на соответствие стандарту (например, ISO)? +1. Ключ должен быть как можно проще, чтобы можно было без трудностей использовать составные ключи. -Это своего рода конвенции, которые нужно сформулировать при проектировании базы -данных. Если требования впоследствии будут разрастаться, можно и нужно вносить -изменения в структуру базы, чтобы поддерживать её в актуальном состоянии. +Это своего рода конвенции, которые нужно сформулировать при проектировании +базы данных. Если требования впоследствии будут разрастаться, можно и нужно +вносить изменения в структуру базы, чтобы поддерживать её в актуальном +состоянии. #### Ограничения @@ -379,26 +385,26 @@ SELECT CASE postcode * У каждой таблицы **должен быть** хотя бы один ключ. * Ограничениям нужно **присваивать** вразумительные имена. Для `UNIQUE`, - `PRIMARY KEY` и `FOREIGN KEY` подобные имена создаются автоматически, поэтому - нужно позаботиться об остальных ограничениях. + `PRIMARY KEY` и `FOREIGN KEY` подобные имена создаются автоматически, + поэтому нужно позаботиться об остальных ограничениях. ##### Расположение и порядок -* Первичный ключ должен быть **объявлен** в самом начале, сразу после оператора - `CREATE TABLE`. +* Первичный ключ должен быть **объявлен** в самом начале, сразу после + оператора `CREATE TABLE`. * Ограничения должны быть **объявлены** строго ниже столбца, с которым они - связаны. Расставьте отступы так, чтобы объявление ограничения начиналось после - названия столбца. + связаны. Расставьте отступы так, чтобы объявление ограничения начиналось + после названия столбца. * В случае ограничений, затрагивающих несколько столбцов, старайтесь **объявлять** их как можно ближе к описанию последнего из них. В крайнем случае объявляйте ограничение в конце тела `CREATE TABLE`. * Ограничения целостности уровня таблицы должны **располагаться** в конце. * **Используйте** алфавитный порядок там, где `ON DELETE` предшествует `ON UPDATE`. -* Внутри запроса можно **выравнивать** каждый уровень по-своему. Например, можно - добавить отступы после названия столбцов, чтобы типы данных начинались с одной - позиции, а затем ещё добавить отступов в нужном количестве, чтобы все - объявления `NOT NULL` тоже были выровнены по левому краю. Подобное +* Внутри запроса можно **выравнивать** каждый уровень по-своему. Например, + можно добавить отступы после названия столбцов, чтобы типы данных начинались + с одной позиции, а затем ещё добавить отступов в нужном количестве, чтобы + все объявления `NOT NULL` тоже были выровнены по левому краю. Подобное форматирование позволит быстрее ориентироваться в коде. ##### Валидация @@ -406,9 +412,9 @@ SELECT CASE postcode * **Используйте** `LIKE` и `SIMILAR TO` для обеспечения целостности строк с известным форматом. * Если диапазон числовых значений для столбца известен, **используйте** - `CHECK()` для предотвращения внесения в базу некорректных данных или скрытого - отсечения части значения слишком больших данных. Обычно проверка делается на - то, что значение больше нуля. + `CHECK()` для предотвращения внесения в базу некорректных данных или + скрытого отсечения части значения слишком больших данных. Обычно проверка + делается на то, что значение больше нуля. * `CHECK()` должен быть **объявлен** как отдельное ограничение для упрощения последующей отладки. @@ -448,8 +454,8 @@ CREATE TABLE staff ( ### Список зарезервированных ключевых слов -Список зарезервированных ключевых слов ANSI SQL (92, 99 and 2003), MySQL версий -с 3 по 5.x, PostgreSQL 8.1, MS SQL Server 2000, MS ODBC и Oracle 10.2. +Список зарезервированных ключевых слов ANSI SQL (92, 99 and 2003), MySQL +версий с 3 по 5.x, PostgreSQL 8.1, MS SQL Server 2000, MS ODBC и Oracle 10.2. ```sql A