Никто не любит писать документацию на код. Никто не любит писать комментарии. Программиста это либо отвлекает (и, следовательно, злит), либо заставляет усомниться в ясности своего кода (и, следовательно, злит). Но все же документация и комментарии нужны — и для коллег, и для потомков.
Есть идеальный способ.
Описания методов и комментарии в коде лучше всего писать под самый-самый конец рабочего дня, когда очень устал и голова уже не соображает. Вот как полностью разряженная батарейка еще вполне способна полчаса поработать в фонарике, так и уставший программист — способен беседовать (письменно).
Почему так?
Это связано с особенностью потребления энергии мозгом. Чтобы писать код, нужно интенсивно и системно думать. Это энергозатратный процесс и он не может продолжаться вечно. Условно говоря, это CPU. Чтобы писать комментарии, нужно вспоминать и говорить (письменно). Оба процесса — бессознательные и как бы рефлекторные, за них отвечают отдельные участки коры головного мозга. Условно — это твой GPU. Более того, написание документации в моменты усталости может стать приятным. Комментирование позволит тебе немного разгрузиться от мыслей о работе, как бы парадоксально это не звучало. Может так стать, что 10 мин написания документации позволят тебе вернуться домой в более свежем состоянии, чем сразу после кода.
Ну и, конечно, важно что сегодня у тебя бесплатно доступна краткосрочная память и тебе не нужно вспоминать.
Важно: этот совет вряд ли поможет в написании какой-либо документации вне кода.