SQM 19/24: Comments Density [software quality crash course] [eng sub]

• Лекция обсуждает комментарии в программном коде, их значение и влияние на качество кода.  

• Брайан Керниган, автор книги "Язык программирования Си", утверждает, что лучшей документацией для кода является его понятная структура.  

• Если код недостаточно хорош, комментарии могут помочь понять его структуру.  

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

• В языке Java для получения количества элементов из массива существует только один способ, что делает код более понятным.  

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

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

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

• В статье не говорится о том, как обрабатывать хвостовые и онлайн комментарии.  

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

• Такие соглашения помогают определить авторство кода и предотвратить его неправильное использование.  

• Обсуждение вопроса о комментариях в коде и их влиянии на количество строк кода на модуль.  

• Упоминается, что в исследованиях не найдено механизмов для вычленения реальных комментариев из кода и их учета в расчетах.  

• Статья Дэвида Парнаса о том, как документация может вредить качеству кода.  

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

• Обсуждение статьи, в которой количество строк кода относится к инвестициям в качество кода.  

• Автор считает, что инвестиции в качество кода - это количество строк комментариев, а не документации.  

• Комментарии к коду - это одалживание качества у будущих поколений программистов.  

• Мартин Фаулер, автор книги о рефакторинге, говорит, что комментарии не должны быть бэт с-мэйлом, но они могут быть дезодорантом, который скрывает плохой запах кода.  

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

• Эндрю Хант, автор книги "Прагматик-программист", критикует идею о том, что хороший код должен иметь много комментариев.  

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

• Он также упоминает, что комментарии могут стать антрасе, если они не соответствуют коду, и это может привести к проблемам в будущем.  

• Исследование показало, что комментарии над классом помогают понять, что делает этот класс, но не помогают понять, как он работает.  

• Рекомендуется не писать комментарии над классом, а сосредоточиться на комментариях над методами.  

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

• Большинство комментариев добавляются после изменения кода, а не во время его написания.  

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

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

• В статье обсуждается процент комментариев в коде, который может быть предиктором качества проекта.  

• Авторы считают, что одной метрикой неправильно подходить к проблеме, и предлагают более тонкие подходы.  

• Авторы делят комментарии на четыре категории: эксплонейшн, препост кондишнс, ворк и другие.  

• Подавляющее большинство комментариев объясняют, как работает код, что является плохим качеством.  

• Авторы критикуют документацию к коду, считая ее неэффективной и бесполезной.  

• Они проводят опрос среди программистов, который показывает, что исходные комментарии и inline-комментарии более интересны для получения информации о коде.  

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

• Категории могут включать информацию о лицензиях, использовании, объяснении и будущем использовании кода.  

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

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

• Авторы анализируют 150 проектов на пяти языках программирования и обнаруживают, что языки программирования имеют разные уровни комментирования.  

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

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

• Упоминается статья о том, что комментарии, написанные людьми, лучше, чем комментарии, написанные компьютерами.  

• Анализ статистики из разных репозиториев с разными языками программирования.  

• Средняя процентная доля комментариев в коде составляет около 18%.  

• Упоминается, что в некоторых проектах процент комментариев может быть выше.  

• Рекомендации по написанию хороших комментариев, включая объяснение непонятных моментов, ссылки на оригинальные источники и избегание дублирования кода.  

• Упоминается технология пазл дривен девелопмент, которая помогает систематизировать код после его исправления.