DocBlock впереди имплементации

Когда-то давно я считал, что вполне себе можно писать код длинной лапшой, а потом причесать его, раздробив на отдельные маленькие методы. В этом случае может возникнуть соблазн вообще не тратить время на такие вещи, или что еще хуже — разбить код на блоки чисто механически, определив условную длину метода в примерные N строк.

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

Такой стиль написания кода может только затруднить понимание происходящего, ведь все методы, полученные таким способом жестко связаны между собой. Как правило, они используют общие состояния и не могут быть использованы в другом контексте.

Конечно при проектировании логичнее описывать логику в сначала в декларациях методов, и только затем дописывая реализацию внутри. Однако все равно возможен соблазн сделать методы, которые будут делать больше, чем одно дело (а может даже больше двух и трех).

Описать заготовку для метода и выбрать для него имя просто, однако просто ли потом сказать русским языком, что он делает?

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

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

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

После написания такого короткого комментария с параметрами и возвращаемым значением уже не остается сомнений в том, чем занимается метод и как он реализуется.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.