Здравствуйте, gress, Вы писали:

G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.

G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились.

G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?

У нас правила такие:
Код комментирует сам себя, но в разумных пределах.
Например, не стоит называть метод слишком длинно в попытке "откомментировать самого себя", типа getFileNamesOrDirectoriesOrThrowExceptionAndLogItAndSendJMSMessageAndAskForDeletion(), это, очевидно, перебор.
Также функциональный стиль неплохо дружит с самодокументируемостью, т.к. функции, даже мелкие, можно называть самодокументируемо (в книге Бэнкса по Реакту есть отличные примеры того, как писать самодокументируемый функциональный код).
Комментарии писать тоже нужно, как раз там, где код остается неочевидным или непонятным, используется какая-то черная магия, костыли и т.д.
Также комментарии имеет смысл писать на TODO для техдолга. В тикеты заводить все техдолги — геморно, а TODO парсятся тем же плагоном дженкинса, позволяя видеть динамику TODO и контролировать тем самым техдолг.
Очевидные комментарии, комментарии ради комментариев — никому не нужны и только засоряют код и затрудняют его рефакторинг (попробуй синкать обильные комменты при рефакторинге — замучаешься).
Также комменты важны в публичном АПИ для описания контракта, хотя и тут в Джаве есть богатый набор аннотаций на все случаи жизни, типа что класс потокобезопасный, параметры nullable и т.д. — всё это можно сделать через аннотации, чем через комментарии. И аннотации лучше, т.к. позволяют подключать инструменты проверки выполнения контракта.

Здравствуйте, gress, Вы писали:

G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.

G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились.

G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?

У нас правила такие:
Код комментирует сам себя, но в разумных пределах.
Например, не стоит называть метод слишком длинно в попытке "откомментировать самого себя", типа getFileNamesOrDirectoriesOrThrowExceptionAndLogItAndSendJMSMessageAndAskForDeletion(), это, очевидно, перебор.
Также функциональный стиль неплохо дружит с самодокументируемостью, т.к. функции, даже мелкие, можно называть самодокументируемо (в книге Бэнкса по Реакту есть отличные примеры того, как писать самодокументируемый функциональный код).
Комментарии писать тоже нужно, как раз там, где код остается неочевидным или непонятным, используется какая-то черная магия (хотя черную магию лучше избегать вовсе), костыли и т.д.
Также комментарии имеет смысл писать на TODO для техдолга. В тикеты заводить все техдолги — геморно, а TODO парсятся тем же плагоном дженкинса, позволяя видеть динамику TODO и контролировать тем самым техдолг.
Очевидные комментарии, комментарии ради комментариев — никому не нужны и только засоряют код и затрудняют его рефакторинг (попробуй синкать обильные комменты при рефакторинге — замучаешься).
Также комменты важны в публичном АПИ для описания контракта, хотя и тут в Джаве есть богатый набор аннотаций на все случаи жизни, типа что класс потокобезопасный, параметры nullable и т.д. — всё это можно сделать через аннотации, чем через комментарии. И аннотации лучше, т.к. позволяют подключать инструменты проверки выполнения контракта.