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

11.01.2018 3298
Количество просмотров
#Разработка

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

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

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

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

 

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

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

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

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

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

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

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

Примеры комментирования 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-формате.
 
Комментирование кода
 

Сформированная документация будет являться удобным инструментом для разработчиков: появится возможность быстрого поиска (встроенного в страницу) и  возможности проваливаться во вложенные элементы документа. То есть, это полноценный сайт, который составлен на основании комментариев в коде.

Пример страницы с описанием класса приведена на принтскрине ниже.

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

Понравилось? Подпишись на обновления!

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