Какой процент текста программы должны занимать комментарии? Комментировать каждую строку? или через одну? Каждая фирма, разрабатывающая программы испытывает прессинг со стороны программистов/кодеров, которые считают что:
в коде переменные и функции имеют значимые названия и поэтому ничего не надо комментировать
специалисту и так должно быть все понятно что тут написано
Я ко всем функциям и объектам дал пояснения. Этого вполне достаточно.
Всякие другие слова, которые объясняют почем комментировать не надо
Но со стороны заказчика и стороны руководства фирмы/проекта чаще наблюдается противоположный подход. Чем больше комментов, тем лучше. Идеально, когда каждая строка содержит пояснение зачем она нужна.
Между ноль комментариев и комментарий к каждой строке лежат все промежуточные состояния. На картинке ниже тексты от двух библиотек. Слева около 20 процентов комментов, а справа менее 5. Обе библиотеки работают без проблем. Ну раз нет проблем, так зачем комменты?
Слева ADAFruit справа idiBus
Разработчик, который сдал готовый отлаженный код, не хочет тратить время на комменты. А я как заказчик текста, хотел бы иметь комментариями минимум 30 процентов текста. Чтобы я мог если надо быстро передать текст другому разработчику. Или на аутсорсинг. Или обновить код через 10 лет. Когда бывший разработчик давно будет хакером на Бали.
Некоторое время назад мы даже сделали прогу, которая вынимала все комменты из текстов программ и выкидывала пробелы и др. мусор и считала процент. И специальный человек проверял эти комменты.
