Стандарт оформления кода как правило описывает

Обновлено: 25.06.2024

Соглашения по оформлению кода команды RSDN

Этот документ описывает единый стиль кода, разработанный командой RSDN. В первую очередь он предназначен для использования в проектах, ведущихся в рамках RSDN. Надеемся, что этот стиль будет полезен всем тем, кто так же ищет удобный единый стиль форматирования исходного кода.

Данные правила являются плодом коллективного труда команды RSDN, но мы позволяем использовать их кому угодно. :) При перепечатке или использовании этих правил в качестве основы для ваших собственных сделайте ссылку на этот документ.

Список терминов

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

Именование идентификаторов

Общие правила

Помните! Код чаще читается, чем пишется, поэтому не экономьте на понятности и чистоте кода ради скорости набора.
Не используйте малопонятные префиксы или суффиксы (например, венгерскую нотацию), современные языки и средства разработки позволяют контролировать типы данных на этапе разработки и сборки.
Не используйте подчеркивание для отделения слов внутри идентификаторов, это удлиняет идентификаторы и затрудняет чтение. Вместо этого используйте стиль именования Кемел или Паскаль.
Старайтесь не использовать сокращения лишний раз, помните о тех, кто читает код.
Старайтесь делать имена идентификаторов как можно короче (но не в ущерб читабельности). Помните, что современные языки позволяют формировать имя из пространств имен и типов. Главное, чтобы смысл идентификатора был понятен в используемом контексте. Например, количество элементов коллекции лучше назвать Count, а не CountOfElementsInMyCollection.
Когда придумываете название для нового, общедоступного (public) класса, пространства имен или интерфейса, старайтесь не использовать имена, потенциально или явно конфликтующие со стандартными идентификаторами.
Предпочтительно использовать имена, которые ясно и четко описывают предназначение и/или смысл сущности.
Старайтесь не использовать для разных сущностей имена, отличающиеся только регистром букв. Разрабатываемые вами компоненты могут быть использованы из языков, не различающих регистр, и некоторые методы (или даже весь компонент) окажутся недоступными.
Старайтесь использовать имена с простым написанием. Их легче читать и набирать. Избегайте (в разумных пределах) использования слов с двойными буквами, сложным чередованием согласных. Прежде, чем остановиться в выборе имени, убедитесь, что оно легко пишется и однозначно воспринимается на слух. Если оно с трудом читается, и вы ошибаетесь при его наборе, возможно, стоит выбрать другое.

Стили использования регистра букв

Паскаль – указание этого стиля оформления идентификатора обозначает, что первая буква заглавная и все последующие первые буквы слов тоже заглавные. Например, B ack C olor, L ast M odified, D ate T ime.
Кэмел – указание этого стиля обозначает, что первая буква строчная, а остальные первые буквы слов заглавные. Например, b order C olor, a ccess T ime, t emplate N ame.

Сокращения

Не используйте аббревиатуры или неполные слова в идентификаторах, если только они не являются общепринятыми. Например, пишите GetWindow, а не GetWin.
Не используйте акронимы, если они не общеприняты в области информационных технологий.
Широко распространенные акронимы используйте для замены длинных фраз. Например, UI вместо User Interface или Olap вместо On-line Analytical Processing.
Если имеется идентификатор длиной менее трех букв, являющийся сокращением, то его записывают заглавными буквами, например System. IO, System.Web. UI. Имена длиннее двух букв записывайте в стиле Паскаль или Кэмел, например Guid, Xml, xmlDocument.

Выбор слов

Пространства имен

Импорт пространств имен (директива using)

Все не вложенные типы (размещаемые в пространствах имен или непосредственно в глобальном пространстве), за исключением делегатов, должны находиться в отдельных файлах.
Старайтесь объявлять вложенные типы в начале внешнего типа.
Старайтесь не делать излишней вложенности типов. Помните, что вложенными должны быть только тесно связанные типы.

Элементы типов (type members)

Элементы типов должны отделяться одной строкой друг от друга. Вложенные типы должны отделяться двумя строками. При объявлении большого количества полей, используемых внутри класса (не публичных), можно опускать пустую строку (особенно если поля отделены XML-комментариями).

Классы/Структуры

Интерфейсы

Используйте описывающее существительное, прилагательное или одно или несколько прилагательных и существительное для идентификатора интерфейса. Например, IComponent – это описывающее существительное, ICustomAttributeProvider – это конкретизированное прилагательными существительное, а IPersistable – это характеризующее прилагательное.
Используйте стиль Паскаль для регистра букв.
Используйте префикс I (заглавная i) для интерфейсов, чтобы уточнить, что тип является интерфейсом. Старайтесь избегать интерфейсов с двумя I в начале, например IIdentifiable. Попробуйте подобрать синоним, например IRecognizable.
Для пары класс-интерфейс, в которой класс является некоторой стандартной или эталонной реализацией интерфейса, используйте одинаковые имена, отличающиеся только префиксом I для интерфейса. Например, IConfigurationManager и ConfigurationManager.

Атрибуты

Класс, являющийся атрибутом, должен иметь суффикс Attribute. Ни один класс, атрибутом не являющийся, не должен иметь такого суффикса. Если семантика класса требует в названии слова что-то вроде Attribute, используйте синонимы, например Descriptor, Sign, Qualifier, Specifier, Declarator.

Перечисления

Непубличные поля (private, protected и protected internal) именуются в стиле Кэмел и начинаются с префикса _.
Публичные поля именуются в соответствии с правилами именования свойств.
Одна декларация должна содержать не более одного поля и должна располагаться на одной строке.

Публичные поля должны в обязательном порядке документироваться XML-комментариями. Желательно снабжать XML-комментариями и непубличные поля.
Обращаясь к публичным полям старайтесь избегать их передачи по ссылке, т.к. велика вероятность того, что в следующих версиях приложения эти поля могут стать свойствами.

Методы

Используйте глаголы или комбинацию глагола и существительных и прилагательных для имен методов.
Используйте стиль Паскаль для регистра букв (вне зависимости от области видимости метода).

Свойства

Используйте существительное или одно или несколько прилагательных и существительное для имени свойства.
Используйте стиль Паскаль для регистра букв.
В подходящих случаях используйте имя свойства, совпадающее с типом его значения. Одним из критериев для применения этого правила является наличие единственного свойства со значением некоторого (нетривиального) типа.
Старайтесь избегать использования имен свойств, совпадающих с названиями каких-либо типов, если значения этих свойств не являются значениями этих типов. В этом случае будет трудно получить доступ к статическим членам типа или значениям перечисления. Например, при использовании конструкции public int Color < get; set; >, обращение Color.Xxx будет рассматриваться как получение свойства Color и затем доступ к свойствам или методам этого значения, которое в данном случае будет являться типа System.Int32.
Рассмотрите возможность включения имени типа в идентификатор свойства, особенно если этот тип – перечисление. Например, OuterBorderStyle , BackColor, SocketFlags.

События

Используйте суффикс EventHandler для делегатов, являющихся типами событий. Другие классы не должны использовать этот суффикс.
Создавая событие в компонентах и control-ах, старайтесь описывать их по следующей схеме. Определите два параметра с именами sender и e. Параметр sender описывает объект, инициировавший событие, и всегда должен быть типа object, даже если возможно использование более конкретного типа. Второй параметр, e, должен содержать состояние и дополнительную информацию, соответствующую событию. Этот параметр должен быть конкретного типа, относящегося к событию.
Делайте тип, описывающий связанную с событием информацию, производным от EventArgs, и используйте суффикс EventArgs . Другие классы, не описывающие информацию о событии, не должны использовать этот суффикс.
Для имен событий старайтесь использовать глаголы, которые описывают производимое над объектом действие (например, Click, GotFocus или FontChanged).
Не используйте суффиксы наподобие On, Before, After для идентификатора события. Используйте соответствующую форму глагола, например Closing перед закрытием и Closed после закрытия.
При описании события также предоставляйте виртуальный protected-метод, который можно переопределить в классе-наследнике. Называйте такой метод OnXxx, где Xxx – имя события. В качестве параметров таких методов не следует передавать sender , так как – это всегда текущий объект (this).
Пытайтесь подобрать стандартный делегат и название для своих событий. Например, если ваш элемент управления должен реагировать на нажатие кнопки мыши, следует использовать стандартное событие Click. Для элементов управления, обычно, такие события уже объявлены в базовом классе Control.

Параметры

Стиль кода

Оформление

Используйте табуляцию , а не пробелы для отступов. В средах типа VS лучше использовать режим табуляции. Его можно настроить в диалоге Options -> Text Editor -> Ваш_любимый_язык ->Tabs: Indenting = Smart, Tabs = Keep Tabs. В общем, это настройки по умолчанию для многих языков.
При форматировании текста (кроме отступа в начале строки) используйте пробелы. Для этого удобно использовать режим Virtual Space, который в VS 2002 настраивается в Options -> Text Editor -> Ваш_любимый_язык -> General.
Избегайте строк длиннее 78 символов, переносите инструкцию на другую строку при необходимости.
При переносе части кода инструкций и описаний на другую строку вторая и последующая строки должны быть отбиты вправо на один отступ (табуляцию).
Оставляйте запятую на предыдущей строке так же, как вы это делаете в обычных языках (русском, например).
Избегайте лишних скобок, обрамляющих выражения целиком. Лишние скобки усложняют восприятие кода и увеличивают возможность ошибки. Если вы не уверены в приоритете операторов, лучше загляните в соответствующий раздел документации.
Не размещайте несколько инструкций на одной строке. Каждая инструкция должна начинаться с новой строки.

Пустые строки

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

Пробелы в строке

После запятой должен быть пробел. После точки с запятой, если она не последняя в строке (напр. в инструкции for), должен быть пробел. Перед запятой или точкой с запятой пробелы не ставятся.
Все операторы должны быть отделены пробелом от операндов с обеих сторон.
Логически связный блок регулярной структуры желательно форматировать в виде таблицы. При этом для выравнивания в таблице следует использовать пробелы, но не табуляцию. Среды типа VS автоматизируют процесс форматирования, вставляя пробелы или табуляции в соотвтествии с пользовательскими настройками. Будьте внимательны и проверяйте конечный результат, включая неотображаемые символы (для VS 2002 и старше – меню Edit->Advanced->View White Space).

Для упрощения работы можно использовать следующий трюк. Таблицу можно сформировать с помощью табуляции, выделить область прямоугольным выделением (Alt + курсор мыши вправо), а затем применить к этой области Edit->Advanced->Untabify Selection.

Набор практик хорошего кода, не зависящих от языка программирования. Примените их, и ваш код будет не только работать, но и читаться.

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

Пишите код так, как будто сопровождать его будет склонный к насилию психопат, который знает, где вы живете

Чем проще читать код, тем проще его сопровождать. Понятный, читаемый код легче тестировать, в нем легче отлавливать ошибки – они не скрываются в его запутанной структуре. Плохо оформленный код неприятно изучать, читать, тестировать, сложно дополнять. Рано или поздно плохой код становится проще переписать.

Эстетическое восприятие кода влияет на удобство работы. Казалось бы, гораздо важнее производительность, возможность модификации, расширения… Но все эти показатели улучшаются, если код соответствует нашему чувству прекрасного. Глядя на качественно написанный код, можно быстро понять алгоритм и то, как работает программа для разных входных данных. Чистый код читается, как хорошо написанная проза: слова превращаются в зрительные образы.

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

Все дороги программиста ведут к документации. В каждом языке существует свой стандарт оформления кода. Для Python используется документ PEP-8, для PHP – стандартные рекомендации PSR-1 и PSR-2, для Java – Java Coding Conventions, для JavaScript – Airbnb JavaScript Style Guide или Google JavaScript Style Guide. Документ для вашего языка вы найдете по поисковому запросу Code Style.

Когда вы работаете в группе разработчиков, нужно использовать принятые в команде правила. Стиль должен быть единым, как будто код был написан одним здравомысленным человеком.

В популярных IDE заложена возможность автоматической настройки стиля кода под стандарты – общие или предложенные командой. Разберитесь, как настроить среду под необходимое оформление. Потраченное время сэкономит многие часы рутинной работы.

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

Как Библиотека программиста, мы не могли обойтись без упоминания замечательной книги Роберта Мартина о чистом коде и анализе программ. В книге приводятся примеры для языка Java, но большинство идей справедливы для любых языков.

Всё что изложено ниже, в значительной мере представляет сжатый конспект этой книги с дополнениями из нашего опыта в проектировании программ. Итак, приступим к практикам.

Содержательность. К выбору названий любых объектов нужно подходить со всей ответственностью. Выразительные имена позволяют писать код, не требующий комментариев.

Полезно не только исходно выбирать ясные имена, но и заменять названия на более удачные, если они нашлись позже. Современные среды программирования позволяют легко заменить название переменной во всём коде, так что это не должно быть проблемой.

Избегайте любых двусмысленностей и ложных ассоциаций. Если в объекте перечисляется список, но сам объект не является списком, нельзя в составе его названия употреблять слово list – это запутывает читающего.

Остерегайтесь малозаметных различий – имена объектов должны существенно отличаться друг от друга. По этой причине плохи длинные имена с повторяющимся элементами – чтобы сличить их друг с другом, тратятся лишние силы и время. Избегайте использования в именах переменных строчной буквы L и прописных I, O – они часто путаются с единицей и нулем.

Путаница также возникает, если несколько синонимичных слов и выражений используются для обозначениях разных сущностей, например, controller , manager и driver .

Правильно выбирайте часть речи. Классы и объекты желательно называть существительными и их комбинациями: Account , WikiPage , HTMLParser . Имена функций и методов лучше представлять глаголами или глагольными словосочетаниями: delete_page , writeField(name) . Для методов чтения/записи и предикатов используйте стандартные префиксы get , set , is .

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

Одно слово для каждой концепции. Для одной и той же идеи, реализующей одну механику, используйте одно слово. Например, для добавления элементов одинаковым образом – метод add . Однако, если механика и семантика изменились, потребуется и другое слово (например, insert , append ), описывающее новую концепцию.

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

Помещайте имена в соответствующий контекст. Например, имена street , house_number , city понятнее смотрятся внутри класса Address .

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

VT100" data-src="https://media.proglib.io/posts/2020/03/17/a6ecfd1ba139b1a74ada4bccadba3d1d." > Внешний вид текстового компьютерного терминала VT100

Блоки if, else, while должны иметь минимальный размер, чтобы информацию о них можно было держать в уме. Старайтесь избегать отрицательных условий – на их восприятие обычно уходит чуть больше времени, чем на положительные. То есть запись if (buffer.shouldCompact()) предпочтительнее записи if (!buffer.shouldNotCompact() .

Правило одной операции. Плохой код пытается сделать слишком много всего, намерения программиста расплываются для читателя. Поэтому стоит ввести важное правило:

Функция должна выполнять только одну операцию, выполнять ее хорошо, и ничего другого она делать не должна.

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

Я люблю, чтобы мой код был элегантным и эффективным. Логика должны быть достаточно прямолинейной, чтобы ошибкам было трудно спрятаться; зависимости — минимальными, чтобы упростить сопровождение; обработка ошибок — полной в соответствии с выработанной стратегией; а производительность — близкой к оптимальной, чтобы не искушать людей загрязнять код беспринципными оптимизациями. Чистый код хорошо решает одну задачу.

Исключения вместо кодов ошибок. Используйте исключения ( try-catch , try-except ) вместо возвращения кодов ошибок. Возвращение кодов приводит к слишком глубокой вложенности.

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

Код читается сверху вниз. По мере чтения уровни абстракции должны меняться равномерно. Каждая функция должна быть окружена функциями единого уровня абстракции.

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

Это непопулярное мнение, но в большинстве случаев комментарии – зло. Код должен быть самодокументированным. Комментарий – всегда признак неудачи: мы не смогли написать код так, что он понятен без комментариев. Проверьте, можно ли выразить свое намерение в самом коде.

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

Однако есть несколько видов комментариев, которые выглядят достаточно оправданными.

TODO-комментарии. Бывает так: нужно было успеть к дедлайну, пришлось писать код быстро, поэтому в нем остались дыры. То есть всё работает, но реализация ущербная. Укажите все недоработки и создайте под них задачи. Каждый комментарий указывает на недоработку или потенциальную уязвимость.

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

Предупреждения о последствиях. Иногда бывает полезно предупредить других программистов о нежелательных последствиях:

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

Бывают такие типы комментариев, которые лучше никогда не делать.

Мертвые функции – идентичные по смыслу предыдущему пункту функции и методы, которые не вызываются в программе. Пользуйтесь системой контроля версий и без зазрений совести удаляйте любой код, который не используется во время выполнения программы.

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

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

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

Качественно организованный код способен внятно рассказать историю без балластных заголовков.

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

Код должен быть максимально линейным. Чем больше вложенность кода, тем сложнее его читать. Следите за тем, как двигаются ваши глаза. В хорошем коде вы двигаетесь строка за строкой, лишь изредка возвращаясь к предыдущим строчкам. Вложенность более трех уровней указывает на то, что с кодом нужно поработать: переписать условия проверок и циклов (использовать return и функциональное программирование), разбить код на меньшие методы.

Тесно связанные концепции, должны располагаться вблизи друг друга. Не заставляйте читателя прыгать между файлами или постоянно скроллить файл. По той же причине переменные нужно объявлять как можно ближе к месту использования. Однако переменные экземпляров лучше объявлять в одном месте, обычно в начале класса, так как в хорошо спроектированном классе переменные используются большинством методов класса.

Пробелы для группировки взаимосвязанных элементов. Пробелы улучшают читаемость кода, если они стоят вокруг операторов присваивания, после запятых при перечислении переменных. В формулах пробелы используются для подчеркивания приоритета: не ставятся между множителями, но отбивают знаки сложения и вычитания.

Отступы. Размер отступов должен соответствовать позиции кода в иерархии. Это общая практика, которая позволяет быстро пропускать области видимости, не относящиеся к текущей ситуации. Не поддавайтесь искушению нарушить правила расстановки отступов для коротких команд.

В системе должны выполняться все тесты. Тесты – главный способ, с помощью которого можно понять, что система контролируема. А только контролируемую систему можно проверить.

Три закона тестирования по методологии TDD. Тестовый код не менее важен, чем код продукта. Соблюдение следующих трех правил позволяет организовать работу так, чтобы тесты охватывали все аспекты кода продукта:

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

F.I.R.S.T. Качественные тесты должны обладать пятью характеристиками, первые буквы которых образуют указанный акроним:

Fast. Тесты должны выполняться быстро.
Independent. Тесты не должны зависеть друг от друга и выполняться в любом порядке.
Repeatable. Тесты должны давать воспроизводимые в любой среде результаты.
Self-validating. Результат выполнения теста – логический признак: тест пройден или нет. Иначе результаты приобретают субъективный характер.
Timely. Тест должен создаваться своевременно. Тесты нужно писать непосредственно перед написанием кода.

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

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

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

Не нужно бездумно следовать догмам. Не переусердствуйте с сокращением кода функций и классов. Всегда руководствуйтесь здравым смыслом.

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

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

Расскажите нам о правилах, которые вы применяете для написания своего программного кода. Какие open source программы, на ваш взгляд, имеют лучшее качество кода?

Восемь общих правил

Существуют правила, которые подойдут для написания кода на любом языке программирования. Только следование им уже повысит качество вашего кода.

Правила кода PHP

На конец 2017 г. действуют стандарты PHP программирования: PSR-2 и PSR-1. Они устанавливают правила синтаксиса, именования, оформления. Весь код должен быть написан единообразно. Это касается пробелов, отступов, скобок, строк.

Чтобы не запоминать все требования стандартов, можно работать в современной среде разработки — PhpStorm, NetBeans и подобных. Они позволяют автоматически форматировать текст в соответствии с правилами.

Отступы

Правильное оформление кода PHP предполагает его простое визуальное восприятие. Оно достигается с помощью отступов и пробелов. Для формирования отступов используйте пробелы, а не знак табуляции. Каждую строку начинайте с четырех пробелов. Код должен идти лесенкой: раскрываться вправо, затем собираться обратно.

Запомните: один отступ = четыре пробела.

Выделяем отступами тело конструкции, тело метода, блоки импорта, аргументы и подобное.

Правильно

Неправильно

Пробелы

между for ( foreach/ while / catch) и (
после ;
между ) и
перед =>
после =>
между try и
между > и catch

После имени метода.
В списке аргументов перед запятыми.
Между ( и именем функции или метода.

Пустая строка

После каждого логического блока.
После определения пространства имен.
После блока импорта. Каждая строка блока должна начинаться с use.

Правильно

Неправильно

Круглые скобки

Не выносим на отдельные строки.
Не ставим пробелы внутри: после ( и перед ).
Ставим пробелы до скобок и после.
Внутри перечисление отделяем пробелами.

Фигурные скобки

Открывающая фигурная скобка выносится на новую строку перед телом метода, для классов.
Открывающая фигурная скобка не выносится на отдельную строку в конструкциях и замыканиях.
Закрывающая скобка > в конструкциях, имени метода, определении метода, классах пишется с новой строки и отделяется одним отступом.

Аргументы

Оформляются двумя способами: в одну строку через запятую или в столбик. Аргументы на одной строке пишутся через запятую внутри круглых скобок. Пробел ставится только после запятой.

Правильно

Неправильно

При оформлении в столбик каждый аргумент пишется с новой строки и отделяется двойным отступом. Первая круглая скобка остается на строке вместе обозначением метода. Вторая круглая скобка выносится в отдельную строку вместе с открывающей фигурной скобкой. Между ними пробел.

Правильно

Неправильно

Конструкция switch case

Конструкцию делим на три уровня: switch, case, echo/break. Каждый уровень начинается с отступа. Таким образом, наш код визуально выглядит состоящим из трех столбцов.

Если в конструкции не используется break, поставьте // no break.

Правильно

Неправильно

Конструкция try catch

Тело try и тело catch отделяются одним отступом. Пробелы нужно поставить:

между try и
между > и catch
между catch и (
между ) и

Catch и скобку > ставим на одну строку.

Правильно

Неправильно

Конструкция if, elseif, else

Операторы и открывающую фигурную скобку пишем на одной строке. Закрывающую фигурную скобку оператора пишем на той же строке, что и оператор. Заключительную фигурную скобку пишем на отдельной строке. Оператор else if пишем как единое слово - elseif. Тело оператора отделяем отступом.

Правильно

Неправильно

Комментарии в коде

Чистый код должен быть правильно закомментирован. К сожалению, встречаются две крайности: подробное комментирование каждой строки и полное отсутствие комментариев. И то, и другое мешает в работе. Избыточное комментирование снижает восприятие кода, отвлекает от понимания его сути. Писать очевидные вещи — тратить свое и чужое время. Иногда из-за слишком подробных комментариев объем кода увеличивается в несколько раз. Закончив с кодом, посмотрите критически. Очевидные и банальные комментарии удалите.

Обратная сторона медали — отсутствие пояснений. Коды со сложной архитектурой, скриптами, с большой вложенностью требуют пометок. В этом случае комментарии помогут быстро ориентироваться в коде другим членам команды. Часто они помогают и самому разработчику кода. Главное — придерживаться золотой середины и комментировать только важные моменты.

Предлагаем чек-лист для самостоятельной проверки чистоты кода. Если вы будете инспектировать чужой код, помните, что программист — творческая профессия. А творческие люди обычно тяжело воспринимают критику. Будьте лояльней.

Легко ли воспринимать код визуально?
Присутствуют ли комментарии? насколько они необходимы?
Соответствует ли код стандартам PSR-1 и PSR-2? Краткая выжимка стандартов приведена в разделе “Правила кода PHP”.
Используете ли вы систему документирования phpDoc или подобную?
Нужно ли делать перерыв в чтении, чтобы разобраться в написанном?
Проведен ли рефакторинг?
Есть ли дублирование в блоках, функциях и пр.?
Понятны ли названия переменных, имена методов и пр.?
Какова длина строк, методов, функций, классов, файла?
Вы искали ошибки и баги?
Как можно еще улучшить код?
Можно ли сделать его короче?
Можно ли сделать его эффективней?

Желательно провести тестирование. Руководствуйтесь тремя принципами:

Тесты должны быть полными.
Тесты должны соответствовать установленным требованиям.
Тесты должны проводиться на нужном уровне тестирования.

Заключение

Код — это не личный захламленный ящик с грудой бумаг. Правильный код — это картотека в Ленинской библиотеке. В нем все структурировано, задокументирована важная информация, есть связи с другими каталогами и библиотеками. Чистый код может разобрать и профи, и начинающий программист. С ним приятно работать, он характеризует уровень мастерства своего разработчика.

Старайтесь следовать принятым правилам, рекомендациям и стандартам. Думайте о тех, кто будет работать с ним после вас. Всегда пробуйте сделать код короче и эффективней. Напишите так, чтобы это понимал не только Бог.

Восемь общих правил

Правила кода PHP

Отступы

Запомните: один отступ = четыре пробела.

Выделяем отступами тело конструкции, тело метода, блоки импорта, аргументы и подобное.

Правильно

Неправильно

Пробелы

между for ( foreach/ while / catch) и (
после ;
между ) и
перед =>
после =>
между try и
между > и catch

После имени метода.
В списке аргументов перед запятыми.
Между ( и именем функции или метода.

Пустая строка

После каждого логического блока.
После определения пространства имен.
После блока импорта. Каждая строка блока должна начинаться с use.

Правильно

Неправильно

Круглые скобки

Не выносим на отдельные строки.
Не ставим пробелы внутри: после ( и перед ).
Ставим пробелы до скобок и после.
Внутри перечисление отделяем пробелами.

Фигурные скобки

Открывающая фигурная скобка выносится на новую строку перед телом метода, для классов.
Открывающая фигурная скобка не выносится на отдельную строку в конструкциях и замыканиях.
Закрывающая скобка > в конструкциях, имени метода, определении метода, классах пишется с новой строки и отделяется одним отступом.

Аргументы

Правильно

Неправильно

Правильно

Неправильно

Конструкция switch case

Если в конструкции не используется break, поставьте // no break.

Правильно

Неправильно

Конструкция try catch

Тело try и тело catch отделяются одним отступом. Пробелы нужно поставить:

между try и
между > и catch
между catch и (
между ) и

Catch и скобку > ставим на одну строку.

Правильно

Неправильно

Конструкция if, elseif, else

Правильно

Неправильно

Комментарии в коде

Легко ли воспринимать код визуально?
Присутствуют ли комментарии? насколько они необходимы?
Соответствует ли код стандартам PSR-1 и PSR-2? Краткая выжимка стандартов приведена в разделе “Правила кода PHP”.
Используете ли вы систему документирования phpDoc или подобную?
Нужно ли делать перерыв в чтении, чтобы разобраться в написанном?
Проведен ли рефакторинг?
Есть ли дублирование в блоках, функциях и пр.?
Понятны ли названия переменных, имена методов и пр.?
Какова длина строк, методов, функций, классов, файла?
Вы искали ошибки и баги?
Как можно еще улучшить код?
Можно ли сделать его короче?
Можно ли сделать его эффективней?

Желательно провести тестирование. Руководствуйтесь тремя принципами:

Тесты должны быть полными.
Тесты должны соответствовать установленным требованиям.
Тесты должны проводиться на нужном уровне тестирования.

Заключение

Photo by John Jackson on Unsplash

– Слушай, эти приватные переменные должны идти после публичных!

– Ни в коем случае! Публичные переменные идут перед приватными!

– Давай спросим Деб, пускай она решает.

– Погодите, а почему эти константы не в camel-case?

Поднимите руки те, кому случалось побывать в подобных ситуациях. ОК, на самом деле можно не поднимать, но что-то мне подсказывает, что многие из вас принимали участие в подобных сценариях.

Поскольку я занимаюсь разработкой последние десять лет, я припоминаю свое участие во многих (возможно, слишком многих) дискуссиях по поводу стандартов оформления кода (code conventions). Эти обсуждения, как бы полезны они ни были, порой перерастают в бесконечные философствования. А затем они начинают захватывать все больше тем, от отступов до структуры папок.

Это может быть болезненно.

Зачем вообще нужен стандарт оформления кода?

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

Для применения стандартов есть множество причин, я остановлюсь на самой важной: читаемости кода.

Что, если я вдруг решу писать только капсом? ВОТ ТАКОЙ ТЕКСТ БУДЕТ ВЫГЛЯДЕТЬ НЕСКОЛЬКО СТРАННО. Вы это непременно заметите, а ваш мозг начнет обдумывать, что изменилось.

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

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

Для того чтобы эффективно и качественно сотрудничать с другими разработчиками, вам нужен общийстандарт оформления кода.

Как выбрать лучший стандарт

Image by TheDigitalArtist on Pixabay

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

При выборе лучшего для себя стандарта я рекомендую делать следующее:

Поискать вдохновение в командах, которыми вы восхищаетесь. Опыт имеет самый высокий приоритет, а некоторые из крупнейших и умнейших компаний публикуют свои руководства по написанию кода. Например, компания Airbnb опубликовала свои стандарты оформления кода для JavaScript и Ruby, а Google – для Java и Python. Нравятся вам эти компании или нет, не слишком важно. Просто если суммировать годы опыта разработчиков в их командах, мы получим какое-то огромное число. Попробуйте применить стандарты подобных компаний в своей команде.
Соберите мнение коллег. Нам, разработчикам, повезло быть частью динамичного сообщества. По факту, наше сообщество это одно из самых больших преимуществ разработки как сферы деятельности вообще. Вы всегда можете найти группы знающих людей на различных платформах для сотрудничества, таких как Slack, Spectrum, Discord. Найти – и опубликовать вопрос относительно стандартов оформления кода. Вы немедленно получите мнение множества разработчиков со всего мира.
Игнорируйте примеры кода. Да, просто игнорируйте их. Я постоянно натыкаюсь на код, который скопировали из ответа на Stackoverflow или откуда-то еще. Люди забывают, что примеры кода, которые они только что скопировали, были, вероятно, написаны в ответ на конкретный технический вопрос или для объяснения работы какой-то библиотеки. В большинстве случаев автор кода в примере не собирался придерживаться каких-то стандартов оформления кода или просто не имел на это времени.

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

А теперь немного философии.

Когда я пришел в Lemonade в качестве единственного фронтенд-разработчика, мне было сложно читать код, написанный моим предшественником. Возможно, он считал такой стиль самым лучшим, но я – нет. Поэтому я переписывал каждый кусочек кода, с которым работал, чтобы он соответствовал моему собственному стандарту. Со временем к команде присоединялось все больше разработчиков, и наши стандарты менялись.

Каждый приходящий разработчик имел свой собственный бэкграунд, со своими стандартами и соглашениями. Чтобы формализовать наши стандарты, мы взяли за точку отсчета стандарт оформления кода на JavaScript от Airbnb. Мы пересмотрели изложенные там правила и изменили или удалили то, с чем были не согласны, а то, что нам понравилось, применили у себя. Мы даже принимали стандарты, которые приносили в команду наши коллеги-разработчики, и интегрировали их в наш главный стандарт.

Image by mohamed_hassan on Pixabay

Процесс оценки каждого стандарта и определения, стоит ли его принять, не только помог улучшить читаемость нашего кода, но и содействовал сплоченности команды.

Итак, горькая правда: нет никакого универсального определения того, какойстандарт оформления кода считать лучшим, просто потому что лучшего стандарта не существует.

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

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

Итак, какой стандарт оформления кода можно считать лучшим? Ответ прост: ваш!

Читайте также: