Commentate on your code

Sometimes a method mixes levels of abstraction, where one section goes into more detail than the rest of the method.  This can make it hard to understand – code can be hard to understand when it’s on only one abstraction level, and introducing an extra level only makes things worse.

One way to detect whether part of a method should be chopped out into a new method is to commentate on your code.  This is just another way of saying that you should work your way through the code from top to bottom, describing what each part does.  This describing could be to another person or to a rubber duck or other inanimate object.

As you’re commentating on your code, if you find yourself mostly saying a sentence per line of code and then saying a sentence that covers several lines of code, this is a clue that this section of the code is at too low a level of abstraction.  For instance, “… and then this bit *sweeps hand over several lines* finds the largest order so far … “ suggests you should chop out those lines of code into a new method called FindLargestOrder.

A slightly hidden example of this is when you have a single if statement, but the condition it’s testing is long and complicated.  So, if you sweep your hand over the whole condition while saying “ … if the order is ready for processing … “ then consider chopping out the condition into a method called IsOrderReady that returns true or false.  The call to the new method commentates on itself.

Commentating on code isn’t the only thing that seems odd to commentate on.  However, like single-stepping every line of every method you change, it’s a practice that can help you improve the code you write and your understanding of it.