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