Код и дизайн

Как понять назначение системы?
Раньше думала, что надо внимательно изучить код, тогда вся система станет автоматически ясна.
Но оказалось, это неверно.
Нужно изучить именно дизайн, документацию. Дизайн - это как раз верхнеуровневое описание системы. Одному дизайну может соответствовать множество реализаций. Поэтому из кода и нельзя понять назначение системы. Но в идеале разработчику нужно стремиться к такой реализации, чтобы ее невозможно было сопоставить ни с каким другим дизайном.

Для закрепления этого принципа решила переписать несколько классов из моего пет-проекта.
Для начала выбрала класс, который представляет собой генератор списка случайных координат. Эти координаты потом используются для построения маршрута на UI. Логика довольно простая - есть метод, который принимает начальную и конечную координату поездки, максимальную скорость и время, с каким интервалом генерируются координаты. Для получения списка точек нужно обратиться к внешнему API, преобразовать результат, а затем просто сохранять координаты в БД с заданным временным интервалом.

Уже на этапе формулирования этой простой логики возникли проблемы. Код был написан 2 года назад, и было сложно вспомнить, что он делает, т.к. метод представлял собой просто очень длинное полотно.

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

Вынесла различные вспомогательные методы в отдельные классы, например логику работы с датами - в класс DateUtil. Теперь метод генерации практически соответствовал логике дизайна, не разбухая от мелких технических деталей.

Циклы заменила на декларативные stream-ы, это сделало код еще более наглядным.

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