Есть ли общие требования к комментированию кода?

Question

[Sharapov]

Как в техзадании обозначить требование комментировать код? Может есть неофициальные стандарты или культура комментирования кода?

Answer 1

[Nikita Dergachov]

Ну по современным тенденциям код не комментируют, а пишут документацию.
https://www.phpdoc.org

Answer 2

[Saboteur]

* Не следует комментировать очевидное. Лучше правильно давать имена методам, классам и переменным
* Если идет исправление бага, бывает удобно указывать номер тикета.
* Комментарии следует писать на английском (исключения могут быть, например 1C, где сам язык программирования русский).
* Для каждого языка могут быть свои требования. php и java имеют встроенные javadoc, phpdoc, которые генерируют документацию, следовательно там уже есть официальный стандарт.

Comments

[Freeman]

Комментарии надо писать на том языке, на котором общается команда и/или будет общаться в будущем. Если компания не планирует выходить в дальнее зарубежье по примеру JetBrains, комменты вполне могут быть и на русском.

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

[Saboteur]

Vapaamies: По возможности, лучше сразу писать на английском. Комментарии получаются короче, нет никаких потенциальных проблем с кодировками. Английского на уровне pre-intermediate более чем достаточно.
Исключения могут быть, но только, если программа полностью нацелена на внутренний рынок, и то. Вдруг захочется потом отдать на аутсорс индусам.

Answer 3

[Иван Сушков]

usejsdoc.org

Answer 4

[malbaron]

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

Читаем как пример как нужно комментировать:
https://github.com/golang/go/blob/master/src/time/...