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

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

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

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

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

 

Плюсы и минусы комментирования кода

Процедура комментирования кода имеет как свои достоинства, так и недостатки.

Так, среди достоинств можно выделить:

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

К недостаткам можно отнести:

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

Примеры комментирования php кода

Для примера мы решили опубликовать некоторые выдержки из наших внутренних регламентов в части программирования на базе Framework Yii, что является наиболее актуальным в рамках ООП (объектно-ориентированного программирования).

По сути, саму структуру комментария можно наглядно представить как:

 

1. Класс

1.1. Константа

1.2. Свойство

1.3. Метод

 

В ходе описания класса рекомендуем комментировать виртуальные свойства класса, которые должны начинаться символом «@» с обязательным добавлением слова «property», что существенно облегчает процедуру написания кода на базе PHP в случае использования IDE PHPStorm. Практический пример таких описаний наглядно представлен ниже:

 

Что касается описания Констант, то при их написании мы рекомендуем использовать верхний регистр:

 

В свою очередь описание Свойства производится посредством определения типа данных с использованием команды «@var», что представлено ниже:

 

Статические свойства могут быть описаны следующим образом:

 

Описание методов модели производится посредством использования таких команд как:

• tableName(),
• rules(),
• attributeLabels(),
• behaviors(),
• beforeSave(), afterSave(),
• beforeFind(), afterFind(),
• beforeDelete(), afterDelete.

Пример описания методов моделей приведен ниже:

 

Отметим, что методы могут содержать комментарии «родительского» класса, что характеризуется параметром @inheritdoc.

Кстати, в представленном ниже примере наглядно представлен и сам комментарий кода:

 

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

Что такое комментирование для менеджера проекта

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

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

1. Предположим, что у нас имеется сайт с разделом, в котором представлена матрица изображений.
2. Отметим, что каждому типу пользователей присвоена собственная «роль» и свой уровень доступа. Среди таких ролей можно выделить: Гостей, Администратора сайта, Юридические и Физические лица и т.д.
3. Таким образом, каждое из представленных изображений в этой матрице может быть доступно или не доступно различным пользователям в зависимости от присвоенной им роли:

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

Класс - описательная часть бизнес-логики. Например, это часть, которая описывает:

- как загрузить объект;

- какие свойства и действия могут быть присвоены этому объекту;

- какие данные и где должны храниться;

- информацию о валидации данных.

1. Константа - не меняющаяся величина. В нашем примере это может быть конкретный путь к директории, где хранятся картинки.
2. Свойство - переменные в классе. Если бы у нас на странице была форма обратной связи, то это были бы поля, которые должен заполнять пользователь.
3. Метод - действия над объектами. Например, процедура загрузки картинки для нашей матрицы.

Горячие клавиши для комментирования кода

Любое написание кода и составление комментариев - это время, а, следовательно,  и материальные затраты. Мы настоятельно рекомендуем вам использовать горячие клавиши с тем, чтобы экономить время.

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

Среди таких «горячих» клавиш следует выделить:

 

Ctrl+Alt+L - выстраивается структура кода;

 

Ctrl+Alt+J - обернуть тег в другой тег, удобно при вёрстке;

 

Двойное нажатие на клавишу Shift - глобальный поиск;

 

Ctrl+Shift+F - поиск в каталоге по всем файлам этого каталога;

 

Ctrl+Shift+R - быстрая замена текста в файлах выбранного каталога;

 

Alt+Insert -  при нахождении в теле необходимого класса можно генерировать геттеры и сеттеры, или перераспределять родительские методы и свойства.

 

Генерация документации на основании комментариев в коде

Многие заказчики часто просят документацию к проекту при этом сами не сознают где и как они будут ей пользоваться.

Мы давно уже перестали создавать большие ГОСТовские документы, которые сложно актуализировать и не понятно, как применить.

Разрабатывая проекты, мы стараемся все емко уместить в двух документах:

1. Техническое задание, которое описывает бизнес-логику разрабатываемого программного решения.
2. Сгенерированная документация для разработчиков на основании оставленных комментариев в коде.

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

1. В качестве примера будем использовать расширение «yii2-apidoc» для фреймворка yii2 (если пишите на другом фреймворке, то есть масса аналогов, например ApiGen, или phpDocumentor.
2. После установки расширения через консоль выполнить команду, которая сформирует документацию в html-формате.