Я аналитик по образованию и стилю мышления. И, если считать дотошно, в самом анализе профессионально уже ровно половину своей жизни - 16+ лет. Если бы я могла дать совет той себе, только начинающей карьеру, то он звучал бы так -

Всегда документируй решение - почему делаешь так, а не иначе; почему остановилась на этой метрике; какую альтернативу рассматривала и почему отмела; почему ограничила знаменатель… зачем зачем почему… дай КОНТЕКСТА будущей себе или тому, кто будет вынужден разгребать твои наработки после тебя! #вформе

Понятный код не объясняет контекст принятых решений. Именно контекст - самое ценное, что исчезает вместе в людьми, которые его создавали.

P.S. В классическом ИТ это правило из категории азбуки. Конечно, я знала о нем давно. Но можно тысячу раз услышать и просто знать, а можно один раз кааак вляпаться и сразу запомнить ;)

Открываем классику «Мифический человеко-месяц» Брукса и читаем , что «самое ценное в разработке - не код, а причины решений».

Гугловский Style Guide тоже прямо указывает, что «основная цель комментариев - предоставить информацию, которую сам код содержать не может. Например,  почему код здесь вообще есть».

В блоге Stack Overflow можно найти, что «плохой комментарий хуже, чем отсутствие комментария. Хороший комментарий объясняет, почему было принято решение, а не что выполняет код строчка за строчкой».