Piousbox

tl;dr: производственный код, тестовый код и документация.

Сертифицированные бухгалтеры обычно пишут вещи дважды, в системе двойного учета. Это помогает избежать некоторых ошибок. Программисты на интерпретируемых языках, такие как я, используются для разработки на основе тестирования (TDD), где каждый элемент функциональности разумно покрыт тестом. В некотором смысле это система двойного входа. Однако, по крайней мере, одна часть отсутствует.

Я обнаружил, что если я не задокументирую функциональность, она как будто исчезает или никогда не существовала. Поэтому я взял за правило писать какую-то документацию для каждого экспонированного бита — будь то часть функциональности или элемент пользовательского интерфейса. По крайней мере, я делаю заметку о работе, проделанной в changelog/worklog. И я делаю это публично. Опубликовать или погибнуть, правильно, и если функциональность реализована никогда не используется, никто не лучше для него.

Описание пользовательского интерфейса в файле README.txt на самом деле достаточно хорошо. Я знаю, потому что я возвращаюсь к чтению их все время. Заполнение файла / папки в репо также оказалось полезным. Если я не помню, как что-то было сделано, возможно, я смогу прочитать это там. И если я напишу документацию, которую никогда не прочитаю - эй, это тоже нормально.

Слишком часто документация отсутствует или является неполной. В то же время, слишком много онлайн-ресурсов описывают вещи, которые не существуют или являются мусором. Почему бы нам не примирить их? Программировать полезные инструменты, *и* писать документацию о том, как их использовать.

Хорошее программное обеспечение заслуживает хорошей документации. Хорошая инженерия — это не просто написание кода. Это также о том, чтобы поделиться своими знаниями и сделать их опыт полезным.