Duplicate code is one of the most pungent code smells. A rule that is often used is to re-structure code once it is duplicated in three or more places.
Common duplication problems, and corresponding solutions are:
Complex classes like GenerateMarkdownDoc often do a lot of different things. To break such a class down, we need to identify a cohesive component within that class. A common approach to find such a component is to look for fields/methods that share the same prefixes, or suffixes. You can also have a look at the cohesion graph to spot any un-connected, or weakly-connected components.
Once you have determined the fields that belong together, you can apply the Extract Class refactoring. If the component makes sense as a sub-class, Extract Subclass is also a candidate, and is often faster.
While breaking up the class, it is a good idea to analyze how other classes use GenerateMarkdownDoc, and based on these observations, apply Extract Interface, too.
1 | <?php |
||
43 | class GenerateMarkdownDoc extends BaseTask implements BuilderAwareInterface |
||
44 | { |
||
45 | use BuilderAwareTrait; |
||
46 | |||
47 | /** |
||
48 | * @var string[] |
||
49 | */ |
||
50 | protected $docClass = []; |
||
51 | |||
52 | /** |
||
53 | * @var callable |
||
54 | */ |
||
55 | protected $filterMethods; |
||
56 | |||
57 | /** |
||
58 | * @var callable |
||
59 | */ |
||
60 | protected $filterClasses; |
||
61 | |||
62 | /** |
||
63 | * @var callable |
||
64 | */ |
||
65 | protected $filterProperties; |
||
66 | |||
67 | /** |
||
68 | * @var callable |
||
69 | */ |
||
70 | protected $processClass; |
||
71 | |||
72 | /** |
||
73 | * @var callable|false |
||
74 | */ |
||
75 | protected $processClassSignature; |
||
76 | |||
77 | /** |
||
78 | * @var callable|false |
||
79 | */ |
||
80 | protected $processClassDocBlock; |
||
81 | |||
82 | /** |
||
83 | * @var callable|false |
||
84 | */ |
||
85 | protected $processMethod; |
||
86 | |||
87 | /** |
||
88 | * @var callable|false |
||
89 | */ |
||
90 | protected $processMethodSignature; |
||
91 | |||
92 | /** |
||
93 | * @var callable|false |
||
94 | */ |
||
95 | protected $processMethodDocBlock; |
||
96 | |||
97 | /** |
||
98 | * @var callable|false |
||
99 | */ |
||
100 | protected $processProperty; |
||
101 | |||
102 | /** |
||
103 | * @var callable|false |
||
104 | */ |
||
105 | protected $processPropertySignature; |
||
106 | |||
107 | /** |
||
108 | * @var callable|false |
||
109 | */ |
||
110 | protected $processPropertyDocBlock; |
||
111 | |||
112 | /** |
||
113 | * @var callable |
||
114 | */ |
||
115 | protected $reorder; |
||
116 | |||
117 | /** |
||
118 | * @var callable |
||
119 | */ |
||
120 | protected $reorderMethods; |
||
121 | |||
122 | /** |
||
123 | * @todo Unused property. |
||
124 | * |
||
125 | * @var callable |
||
126 | */ |
||
127 | protected $reorderProperties; |
||
128 | |||
129 | /** |
||
130 | * @var string |
||
131 | */ |
||
132 | protected $filename; |
||
133 | |||
134 | /** |
||
135 | * @var string |
||
136 | */ |
||
137 | protected $prepend = ""; |
||
138 | |||
139 | /** |
||
140 | * @var string |
||
141 | */ |
||
142 | protected $append = ""; |
||
143 | |||
144 | /** |
||
145 | * @var string |
||
146 | */ |
||
147 | protected $text; |
||
148 | |||
149 | /** |
||
150 | * @var string[] |
||
151 | */ |
||
152 | protected $textForClass = []; |
||
153 | |||
154 | /** |
||
155 | * @param string $filename |
||
156 | * |
||
157 | * @return static |
||
158 | */ |
||
159 | public static function init($filename) |
||
163 | |||
164 | /** |
||
165 | * @param string $filename |
||
166 | */ |
||
167 | public function __construct($filename) |
||
171 | |||
172 | /** |
||
173 | * Put a class you want to be documented. |
||
174 | * |
||
175 | * @param string $item |
||
176 | * |
||
177 | * @return $this |
||
178 | */ |
||
179 | public function docClass($item) |
||
184 | |||
185 | /** |
||
186 | * Using a callback function filter out methods that won't be documented. |
||
187 | * |
||
188 | * @param callable $filterMethods |
||
189 | * |
||
190 | * @return $this |
||
191 | */ |
||
192 | public function filterMethods($filterMethods) |
||
197 | |||
198 | /** |
||
199 | * Using a callback function filter out classes that won't be documented. |
||
200 | * |
||
201 | * @param callable $filterClasses |
||
202 | * |
||
203 | * @return $this |
||
204 | */ |
||
205 | public function filterClasses($filterClasses) |
||
210 | |||
211 | /** |
||
212 | * Using a callback function filter out properties that won't be documented. |
||
213 | * |
||
214 | * @param callable $filterProperties |
||
215 | * |
||
216 | * @return $this |
||
217 | */ |
||
218 | public function filterProperties($filterProperties) |
||
223 | |||
224 | /** |
||
225 | * Post-process class documentation. |
||
226 | * |
||
227 | * @param callable $processClass |
||
228 | * |
||
229 | * @return $this |
||
230 | */ |
||
231 | public function processClass($processClass) |
||
236 | |||
237 | /** |
||
238 | * Post-process class signature. Provide *false* to skip. |
||
239 | * |
||
240 | * @param callable|false $processClassSignature |
||
241 | * |
||
242 | * @return $this |
||
243 | */ |
||
244 | public function processClassSignature($processClassSignature) |
||
249 | |||
250 | /** |
||
251 | * Post-process class docblock contents. Provide *false* to skip. |
||
252 | * |
||
253 | * @param callable|false $processClassDocBlock |
||
254 | * |
||
255 | * @return $this |
||
256 | */ |
||
257 | public function processClassDocBlock($processClassDocBlock) |
||
262 | |||
263 | /** |
||
264 | * Post-process method documentation. Provide *false* to skip. |
||
265 | * |
||
266 | * @param callable|false $processMethod |
||
267 | * |
||
268 | * @return $this |
||
269 | */ |
||
270 | public function processMethod($processMethod) |
||
275 | |||
276 | /** |
||
277 | * Post-process method signature. Provide *false* to skip. |
||
278 | * |
||
279 | * @param callable|false $processMethodSignature |
||
280 | * |
||
281 | * @return $this |
||
282 | */ |
||
283 | public function processMethodSignature($processMethodSignature) |
||
288 | |||
289 | /** |
||
290 | * Post-process method docblock contents. Provide *false* to skip. |
||
291 | * |
||
292 | * @param callable|false $processMethodDocBlock |
||
293 | * |
||
294 | * @return $this |
||
295 | */ |
||
296 | public function processMethodDocBlock($processMethodDocBlock) |
||
301 | |||
302 | /** |
||
303 | * Post-process property documentation. Provide *false* to skip. |
||
304 | * |
||
305 | * @param callable|false $processProperty |
||
306 | * |
||
307 | * @return $this |
||
308 | */ |
||
309 | public function processProperty($processProperty) |
||
314 | |||
315 | /** |
||
316 | * Post-process property signature. Provide *false* to skip. |
||
317 | * |
||
318 | * @param callable|false $processPropertySignature |
||
319 | * |
||
320 | * @return $this |
||
321 | */ |
||
322 | public function processPropertySignature($processPropertySignature) |
||
327 | |||
328 | /** |
||
329 | * Post-process property docblock contents. Provide *false* to skip. |
||
330 | * |
||
331 | * @param callable|false $processPropertyDocBlock |
||
332 | * |
||
333 | * @return $this |
||
334 | */ |
||
335 | public function processPropertyDocBlock($processPropertyDocBlock) |
||
340 | |||
341 | /** |
||
342 | * Use a function to reorder classes. |
||
343 | * |
||
344 | * @param callable $reorder |
||
345 | * |
||
346 | * @return $this |
||
347 | */ |
||
348 | public function reorder($reorder) |
||
353 | |||
354 | /** |
||
355 | * Use a function to reorder methods in class. |
||
356 | * |
||
357 | * @param callable $reorderMethods |
||
358 | * |
||
359 | * @return $this |
||
360 | */ |
||
361 | public function reorderMethods($reorderMethods) |
||
366 | |||
367 | /** |
||
368 | * @param callable $reorderProperties |
||
369 | * |
||
370 | * @return $this |
||
371 | */ |
||
372 | public function reorderProperties($reorderProperties) |
||
377 | |||
378 | /** |
||
379 | * @param string $filename |
||
380 | * |
||
381 | * @return $this |
||
382 | */ |
||
383 | public function filename($filename) |
||
388 | |||
389 | /** |
||
390 | * Inserts text at the beginning of markdown file. |
||
391 | * |
||
392 | * @param string $prepend |
||
393 | * |
||
394 | * @return $this |
||
395 | */ |
||
396 | public function prepend($prepend) |
||
401 | |||
402 | /** |
||
403 | * Inserts text at the end of markdown file. |
||
404 | * |
||
405 | * @param string $append |
||
406 | * |
||
407 | * @return $this |
||
408 | */ |
||
409 | public function append($append) |
||
414 | |||
415 | /** |
||
416 | * @param string $text |
||
417 | * |
||
418 | * @return $this |
||
419 | */ |
||
420 | public function text($text) |
||
425 | |||
426 | /** |
||
427 | * @param string $item |
||
428 | * |
||
429 | * @return $this |
||
430 | */ |
||
431 | public function textForClass($item) |
||
436 | |||
437 | /** |
||
438 | * {@inheritdoc} |
||
439 | */ |
||
440 | public function run() |
||
465 | |||
466 | /** |
||
467 | * @param string $class |
||
468 | * |
||
469 | * @return null|string |
||
470 | */ |
||
471 | protected function documentClass($class) |
||
514 | |||
515 | /** |
||
516 | * @param \ReflectionClass $reflectionClass |
||
517 | * |
||
518 | * @return string |
||
519 | */ |
||
520 | protected function documentClassSignature(\ReflectionClass $reflectionClass) |
||
545 | |||
546 | /** |
||
547 | * @param \ReflectionClass $reflectionClass |
||
548 | * |
||
549 | * @return string |
||
550 | */ |
||
551 | protected function documentClassDocBlock(\ReflectionClass $reflectionClass) |
||
562 | |||
563 | /** |
||
564 | * @param \ReflectionMethod $reflectedMethod |
||
565 | * |
||
566 | * @return string |
||
567 | */ |
||
568 | protected function documentMethod(\ReflectionMethod $reflectedMethod) |
||
592 | |||
593 | /** |
||
594 | * @param \ReflectionProperty $reflectedProperty |
||
595 | * |
||
596 | * @return string |
||
597 | */ |
||
598 | protected function documentProperty(\ReflectionProperty $reflectedProperty) |
||
621 | |||
622 | /** |
||
623 | * @param \ReflectionProperty $reflectedProperty |
||
624 | * |
||
625 | * @return string |
||
626 | */ |
||
627 | protected function documentPropertySignature(\ReflectionProperty $reflectedProperty) |
||
639 | |||
640 | /** |
||
641 | * @param \ReflectionProperty $reflectedProperty |
||
642 | * |
||
643 | * @return string |
||
644 | */ |
||
645 | protected function documentPropertyDocBlock(\ReflectionProperty $reflectedProperty) |
||
667 | |||
668 | /** |
||
669 | * @param \ReflectionParameter $param |
||
670 | * |
||
671 | * @return string |
||
672 | */ |
||
673 | protected function documentParam(\ReflectionParameter $param) |
||
693 | |||
694 | /** |
||
695 | * @param string $doc |
||
696 | * @param int $indent |
||
697 | * |
||
698 | * @return string |
||
699 | */ |
||
700 | public static function indentDoc($doc, $indent = 3) |
||
715 | |||
716 | /** |
||
717 | * @param \ReflectionMethod $reflectedMethod |
||
718 | * |
||
719 | * @return string |
||
720 | */ |
||
721 | protected function documentMethodSignature(\ReflectionMethod $reflectedMethod) |
||
742 | |||
743 | /** |
||
744 | * @param \ReflectionMethod $reflectedMethod |
||
745 | * |
||
746 | * @return string |
||
747 | */ |
||
748 | protected function documentMethodDocBlock(\ReflectionMethod $reflectedMethod) |
||
783 | } |
||
784 |
If you implement
__call
and you know which methods are available, you can improve IDE auto-completion and static analysis by adding a @method annotation to the class.This is often the case, when
__call
is implemented by a parent class and only the child class knows which methods exist: