именно так. Я прекрасно вижу, что делают функции, но напрочь забыл картину целиком. Восстановить можно, но вопрос в оптимизации этого процесса. Особенно касается случая, когда модуль не дописан до конца.

В коммент писать, иначе никак

Дока она ведь зачем нужна:
Если ты новенький в проекте, то дока немного вводит в курс дела
Если ты старенький, чтобы ронять что происходит и где можно поправить или ещё раз убедится что все нормально

Если функция берёт производную — ну вот как ты её опишешь? Цитировать википедию? Вставить ссылку на википедию? Так если человек в институте не был, так не поможет википедия — это надо начинать с азов математики. Единственное, что можно — вынести магию в отдельный файл, и оставить программисту только понятный интерфейс. Например, tjCompress2() - принимает на вход битмап, выдаёт на выхиде жипег. Всё. Таблицы Хаффмана пусть остаются там, где их никто не видит, во избежание психологических травм )

ну вот и надо писать что делает модуль; если используется ООП - давать классам и методам понятные имена, ну и всё такое, очень может помочь потом вникнуть в происходящее

Это если у тебя проект на 10к строк...

А на меньшее количество вроде вообще одного программиста и недели хватит. Ну во всяком случае если код не обезьяна писала

Как проект разрастается, прошел через несколько лапок - без документации и гита/свн - никак

Время программиста дорого

Без гита обычно вообще жопа

Кстати, readme.md и писать там всю магию

Я обычно делаю docs/ и туда записываю какие-то инструкции иди сложные моменты. Но доки там у меня нет)

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

у нас на работе коду уже на сотни тысяч строк, но документации нет вообще, разрабы всегда копаются по классам

но к их чести - все компоненты устроены по единому принципу, есть в них каталоги data/database/daos/cache, все классы называются единообразно и всё такое, реально сразу понятно куда тыкаться чтобы что-то найти

Повезло с архитектором

Что есть daos?

Как будто у фрилансеров или у студентов времени больше) у всех его мало

это какие-то абстрактные классы, там идея в том, что все данные кладутся в кэш, который асинхронно пишется в базу, асинхронно экспайрится, есть асинхронные очереди на добавление/изменение данных в кэше или в базе и всё такое

Звучит крайне страшно и не идемпотентно