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

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

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

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

    Решил напомнить несколько советов, которых нужно придерживаться при написании комментариев к коду.

    Несколько советов

    0. Приоритетная задача каждого программиста — это актуальные комментарии.
    1. «Пишите код так, как будто сопровождать его будет склонный к насилию психопат, который знает, где вы живете» — Макконнелл, Стив.
    2. Комментируем код именно для себя (грамотно, чтоб и другие поняли).
    3. Не нужно комментировать очевидные вещи.
    4. Комментарий должен дополнять код, а не перефразировать его.
    5. Если код использует стандартные функции, конструкции или классы описанные в азах языка, то не тратьте свое время, в данном случае поможет только правильно оформленный код.
    6. Комментарий к фрагменту кода, нужно писать с тем же отступом, что и у комментируемого кода.
    7. Вредная привычка многих — разговаривать с кем-то в комментарии, комментарий должен быть коротким и четким.
    8. В комментарии можно оставить задачу на потом, которую по каким-то причинам не выполнили в настоящий момент. Такие заметки хранить в отдельном файле не советую, потому как, кроме Вас над кодом может работать еще кто-то и проще, если он будет на месте видеть, где и что не доделано, но будет реализовано. Возможно будут найдены более актуальные решения.
    9. Хорошая практика — в начале файла кратко описать его назначение.
    10. Новые классы и функции — желательно описать, какие и от куда попадают входящие данные и какая цель.
    11. Дабы избавится от лишних комментариев кода, можно выбирать название классов, функций, объектов и т.п. по назначению.

    Вывод

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

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

    Экономьте свое время и пощадите тех кто будет работать над вашим кодом.

    P.S. Поздравляю всех с прошедшим праздником программиста, желаю, чтоб ваши интересы и ваша работа — были одним целым. Чтоб клиенты были отличные и любое начатое дело доводилось до успеха.
    Ads
    AdBlock has stolen the banner, but banners are not teeth — they will be back

    More

    Comments 13

      +1
      Спасибо за пост и поздравления! =)
      От себя хотел бы добавить исходя из практики — надо добавлять ещё дату в комментарий и кто писал его. Просто пока работал в банке и модули изменяли несколько программистов даже при наличии SVN код потом разбирать сложно было. Удобнее когда каждый соблюдал простое правило, что-то типа:
      \\ 01.01.2011 Odu изменение инструмента формирования счетов
      дата сразу акцентирует внимание когда были внесены изменения в код, и при желании можно обычным поиском найти все изменения за конкретную дату или отследить как и что изменялось
      ник позволяет определить кем вносились изменения, что бы потом определиться зачем или с кем идти с вопросами или кулаками =)
        +1
        Еще можно дополнять комментарии номером задачи из таск-трекера. «Для чего тут так сделано» будет намного проще определить. А заодно и кто и когда ))
          +2
          git/svn annotate
            –1
            В компании, где работаю принято комментировать еще и замены кода:
            // Компания, Сотрудник, Дата
            // Замена
            // Было
            // <Старый код>
            // Стало
            <Новый код>

            Да, этот подход приводит к некоторому нагромождению, но зато достаточно удобно поиском посмотреть все внесенные доработки и при необходимости вернуть все назад.
              +16
              Для этого придумали системы контроля версий, вы делаете эту работу вручную, ужас, ужас, ужас
                0
                Да, т.к. работаю с 1С и не все клиенты используют хранилище конфигурации (своего рода система контроля версий).
                0
                Ужасно конечно.
                Такие комментарии 30-50% рабочего времени занимают, а толку от них 5% :(
                +1
                В SVN Blame есть.
                В других тоже наверное.Построчно показывает кто автор и ревизию.
                +4
                Возможно вы где-то имели это ввиду, но я бы добавил еще такой совет:

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

                Врядли это понятно, приведу примеры (слегка утрированные):

                «Далее мы перебираем массив такой-то, суммируем поле price у элементов с state=1» — плохо
                «Возвращем false если 8-й бит поля User->Rights равен нулю» — плохо

                «Далее мы суммируем цены актуальных товаров на складе» — хорошо
                «Дальнейшие действия доступны только администратору» — хорошо

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

                  +6
                  Согласен с идеей, но не согласен с примерами:

                  «Далее мы суммируем цены актуальных товаров на складе» — плохо
                  this.countSum( warehouse.getActualItems() ); // хорошо
                  


                  «Дальнейшие действия доступны только администратору» — плохо
                  if (user.hasRole( 'admin' )) {
                      // хорошо
                  }
                  
                    0
                    Как я сказал, примеры утрированны.

                    Хороший код, как известно, в комментариях не нуждается. Это продемонстрировали вы ))
                  0
                  У нас таск-трекер не сразу появился. Потом я, конечно, стал добавлять номер задачи с helpdesk-а
                  Спасибо за уточнение, кстати, не подумал дописать)
                    0
                    И конечно же следите за кодегайдом своей организации!

                    Only users with full accounts can post comments. Log in, please.