Vlad's Roam Garden

Powered by 🌱Roam Garden

all code in the function should be at the same level of abstraction

seedling clean code broken windows theory function level of abstraction make-public

Which is the level one below the operation described by the name of the function.

reference

If a function does only those steps that are one level below the stated name of the function, then the function is doing one thing. After all, the reason we write functions is to decompose a larger concept (in other words, the name of the function) into a set of steps at the next level of abstraction.
Clean Code: 84

G34: Functions Should Descend Only One level of abstraction
The statements within a function should all be written at the same level of abstraction, which should be one level below the operation described by the name of the function. This may be the hardest of these heuristics to interpret and follow. Though the idea is plain enough, humans are just far too good at seamlessly mixing level of abstraction. Consider, for example, the following code taken from FitNesse: 
 public String render() throws Exception {
     StringBuffer html = new StringBuffer(“<hr”);
     if(size > 0)
       html.append(” size=\“”).append(size + 1).append(”\“”);
     html.append(“>”);

     return html.toString();
   }
A moment’s study and you can see what’s going on. This function constructs the HTML tag that draws a horizontal rule across the page. The height of that rule is specified in the size variable.
Now look again. This method is mixing at least two level of abstraction. The first is the notion that a horizontal rule has a size. The second is the syntax of the HR tag itself. This code comes from the HruleWidget module in FitNesse. This module detects a row of four or more dashes and converts it into the appropriate HR tag. The more dashes, the larger the size.
I refactored this bit of code as follows. Note that I changed the name of the size field to reflect its true purpose. It held the number of extra dashes. 
   public String render() throws Exception
   {
     HtmlTag hr = new HtmlTag(“hr”);
     if (extraDashes > 0)
       hr.addAttribute(“size”, hrSize(extraDashes));
     return hr.html();
   }

   private String hrSize(int height)
   {
     int hrSize = height + 1;
     return String.format(“%d”, hrSize);
   }
This change separates the two level of abstraction nicely. The render function simply constructs an HR tag, without having to know anything about the HTML syntax of that tag. The HtmlTag module takes care of all the nasty syntax issues.
Indeed, by making this change I caught a subtle error. The original code did not put the closing slash on the HR tag, as the XHTML standard would have it. (In other words, it emitted <hr> instead of <hr/>.) The HtmlTag module had been changed to conform to XHTML long ago.
Separating level of abstraction is one of the most important functions of refactoring, and it’s one of the hardest to do well. As an example, look at the code below. This was my first attempt at separating the abstraction levels in the HruleWidget.render method. 
   public String render() throws Exception
   {
     HtmlTag hr = new HtmlTag(“hr”);
     if (size > 0) {
       hr.addAttribute(“size”, “”+(size+1));
     }
     return hr.html();
   }
My goal, at this point, was to create the necessary separation and get the tests to pass. I accomplished that goal easily, but the result was a function that still had mixed level of abstraction. In this case the mixed levels were the construction of the HR tag and the interpretation and formatting of the size variable. This points out that when you break a function along lines of abstraction, you often uncover new lines of abstraction that were obscured by the previous structure.
Clean Code: 411

Mixing level of abstraction within a function is always confusing. Readers may not be able to tell whether a particular expression is an essential concept or a detail. Worse, like broken windows theory, once details are mixed with essential concepts, more and more details tend to accrete within the function.
Clean Code: 85

G30: Functions Should Do One Thing
It is often tempting to create functions that have multiple sections that perform a series of operations. Functions of this kind do more than one thing, and should be converted into many smaller functions, each of which does one thing.
For example: 
   public void pay() {
     for (Employee e : employees) {
       if (e.isPayday()) {
         Money pay = e.calculatePay();
         e.deliverPay(pay);
       }
     }
   }
This bit of code does three things. It loops over all the employees, checks to see whether each employee ought to be paid, and then pays the employee. This code would be better written as: 
   public void pay() {
     for (Employee e : employees)
       payIfNecessary(e);
   }

   private void payIfNecessary(Employee e) {
     if (e.isPayday())
       calculateAndDeliverPay(e);
   }

   private void calculateAndDeliverPay(Employee e) {
     Money pay = e.calculatePay();
     e.deliverPay(pay);
   }
Each of these functions does one thing. (See “Do One Thing” on page 35.)
Clean Code: 409

Referenced in

all code in the function should be at the same level of abstraction