Указываются ли комментарии в листинге кода?

Question

[Nulltiton]

Указываются ли комментарии в листинге кода? В каждом нормативном документе написано по-разному.

Answer 1

[Александр Нестеров]

В каждом нормативном документе написано по разному

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

• Сложность проекта
  
• Пишите ли вы сами/в команде
  
• Возможна ли потом доработка (в т.ч. - совершенно другими разработчиками)
  

(Это основные, но далеко не единственные)

Answer 2

[mayton2019]

К сожалению комметарии всегда не формализованы. И разработчик не являясь техно-писателем не может их написать настолько грамотно чтобы они представляли интерес для заказчика. Поэтому для заказчика пишутся отдельно сопроводительные документы по софту. А комментарии в коде разрабы пишут для самих себя типа "todo: оптимизировать".

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

Существуют системы авто-генерации документации типа Javadoc, Doxia, но они не получили распространения как в области техно-писательства именно по причинам которые я описал выше.

Answer 3

[res2001]

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

Answer 4

[Griboks]

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