Как насчёт холиварчика? Есть аргументы за/против комментариев/заметок в коде?
* заметки в коде помогают решить проблему передачи знаний между людьми, и самому себе в будущее. Да, в командах знания стремятся в одну/две головы из команды, а наружу со скрипом.
* "неопытные" разработчики могут помогать опытным исследуя параллельно какие-то куски кода и покрывая их заметками. Да, мы все становимся неопытными, когда влезаем в рефакторинг давнокода.
* Можно обозвать заметки страшным словом документация. Ведь есть железный аргумент - документация устаревает, её некому и некогда поддерживать. Несмотря на то, что заметки зачастую исправляются очень редко.
* Можно сказать, что комментарии раздувают размер файлов, хотя ничего не мешает ограничить их размер, например, одной строчкой JSDoc. Ведь неудобно же читать лёжа с 15 дюймового ноута.
* Можно ли разрешить писать заметки в отдельные *.d.ts файлы? Наверное, нет. Ведь есть риск, что это станет обязательным. Ну и у нас же не какой-то фреймворк. Хотя, вообще-то уже несколько человеко-лет в код накапало.