День 1061.
Одно из Тех Самых Однострочных Исправлений
В команде Roslyn я научился писать длинные описательные комментарии для сложных мест. Я абсолютно уверен, что подобные комментарии - ценная практика и инклюзивная практика для тех, кто плохо знаком с кодовой базой.

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

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

Если я потратил часы своего драгоценного времени на то, чтобы получить эти знания, мне лучше поместить их в код вместе с сообщением коммита, чтобы их было нелегко потерять.
- Kirill Osenkov

А как вы относитесь к комментариям?

Источник