Просто хотелось понять как лучше документировать код.
Тогда вы уж очень издалека зашли. Причем не у меня одного возникло такое впечатление:
Нда... изначально в вопросе темы это было как-то трудно уловить.
Как общее правило воспользуйтесь советом
RXL:
Лучшая документация кода - читаемый код!
Как способ достижения этой цели используйте концепцию "грамотного кодирования" Дональда Кнута. Помогут в выработке стиля также рекомендации Стивена Макконнелла ("Совершенный код" и др.), "дядюшки Боба" Роберта Мартина ("Чистый код" и др.) и множество других книг на эту тему, сейчас их предостаточно. Некоторые из них найдете на моей "
Книжной полке".
Сторонники agile подхода считают, что очень хорошую документацию представляют собой тесты (особенно если разработка ведется через TDD/BDD/ATDD и иже с ними). Я с ними полностью солидарен.
Не забывайте про рефакторинг. Каждый "запах" делает код менее привлекательным и, следовательно, хуже читаемым.
Изучайте и применяйте паттерны. Они прекрасно документированы и известны профессионалам. Достаточно сказать "здесь использован паттерн такой-то", и можно дальше не комментировать, все и так понятно. Главное - применять их
осознанно (иначе получится собачий цирк наподобие того, который недавно устроил один из новичков под видом паттерна "Декоратор").
Хороший тест на читаемость - ревизия кода опытными разработчиками, проверено лично на практике. Со стороны многие вещи гораздо виднее. Устраните все обоснованные замечания - и код примет совершенно другой вид.
Если посмотрите на проблему еще ширше, выяснится, что кодирование - не самая сложная часть разработки (как укладка кирпичей не есть суть архитектуры, хотя от качества укладки, конечно, сильно зависит качество здания в целом). Понадобится документировать не только сам код, но и требования заказчика, и архитектуру решения, которая должна обеспечить воплощение этих требований. Тут весьма кстати придется UML и архитектурная модель "4+1".
Остается для меня непознанным единственный вопрос: при чем тут Unix?