Vlad's Roam Garden

prefer structure over convention

seedling clean code architecture constraint make-public

People can ignore conventions or not be aware of them. On the other hand, structural constraints in the code are far more discoverable and automatically enforceable.

It's usually easy to get your tools to tell you what you're doing wrong and how you can fix it.

Arguably it's another view on knowledge in the world vs knowledge in the head

Structure sometimes can be too rigid though

in the spirit of the example below - think all the classes in java throwing "not implemented" error.

reference

G27: Structure over Convention

Enforce design decisions with structure over convention. Naming conventions are good, but they are inferior to structures that force compliance. For example, switch/cases with nicely named enumerations are inferior to base classes with abstract methods. No one is forced to implement the switch/case statement the same way each time; but the base classes do enforce that concrete classes have all abstract methods implemented.

prefer structure over convention

Clean Code: 409

G22: Make Logical Dependencies Physical If one module depends upon another, that dependency should be physical, not just logical. The dependent module should not make assumptions (in other words, logical dependencies) about the module it depends upon. Rather it should explicitly ask that module for all the information it depends upon.

For example, imagine that you are writing a function that prints a plain text report of hours worked by employees. One class named HourlyReporter gathers all the data into a convenient form and then passes it to HourlyReportFormatter to print it. (See Listing 17-1 .)

Listing 17-1 HourlyReporter.java

   public class HourlyReporter {
     private HourlyReportFormatter formatter;
     private List<LineItem> page;
     private final int PAGE_SIZE = 55;
     public HourlyReporter(HourlyReportFormatter formatter) {
       this.formatter = formatter;
       page = new ArrayList<LineItem>();
     }

     public void generateReport(List<HourlyEmployee> employees) {
       for (HourlyEmployee e : employees) {
         addLineItemToPage(e);
         if (page.size() == PAGE_SIZE)
           printAndClearItemList();
       }
       if (page.size() > 0)
         printAndClearItemList();
     }

     private void printAndClearItemList() {
       formatter.format(page);
       page.clear();
     }
     
     private void addLineItemToPage(HourlyEmployee e) {
       LineItem item = new LineItem();
       item.name = e.getName();
       item.hours = e.getTenthsWorked() / 10;
       item.tenths = e.getTenthsWorked() % 10;
       page.add(item);
     }
     public class LineItem {
       public String name;
       public int hours;
       public int tenths;
     }
   }

This code has a logical dependency that has not been physicalized. Can you spot it? It is the constant PAGE_SIZE. Why should the HourlyReporter know the size of the page? Page size should be the responsibility of the HourlyReportFormatter.

The fact that PAGE_SIZE is declared in HourlyReporter represents a misplaced responsibility [G17] that causes HourlyReporter to assume that it knows what the page size ought to be. Such an assumption is a logical dependency. HourlyReporter depends on the fact that HourlyReportFormatter can deal with page sizes of 55. If some implementation of HourlyReportFormatter could not deal with such sizes, then there would be an error.

We can physicalize this dependency by creating a new method in HourlyReport-Formatter named getMaxPageSize(). HourlyReporter will then call that function rather than using the PAGE_SIZE constant.

Clean Code: 404

G31: Hidden Temporal Couplings

Temporal couplings are often necessary, but you should not hide the coupling. Structure the arguments of your functions such that the order in which they should be called is obvious. Consider the following:

   public class MoogDiver {
     Gradient gradient;
     List<Spline> splines;

     public void dive(String reason) {
       saturateGradient();
       reticulateSplines();
       diveForMoog(reason);
     }
     …
   }

The order of the three functions is important. You must saturate the gradient before you can reticulate the splines, and only then can you dive for the moog. Unfortunately, the code does not enforce this temporal coupling. Another programmer could call reticulateSplines before saturateGradient was called, leading to an UnsaturatedGradientException. A better solution is:

   public class MoogDiver {
     Gradient gradient;
     List<Spline> splines;

     public void dive(String reason) {
       Gradient gradient = saturateGradient();
       List<Spline> splines = reticulateSplines(gradient);
       diveForMoog(splines, reason);
     }
     …
   }

This exposes the temporal coupling by creating a bucket brigade. Each function produces a result that the next function needs, so there is no reasonable way to call them out of order.

You might complain that this increases the complexity of the functions, and you’d be right. But that extra syntactic complexity exposes the true temporal complexity of the situation.

Note that I left the instance variables in place. I presume that they are needed by private methods in the class. Even so, I want the arguments in place to make the temporal coupling explicit.

Clean Code: 410

Referenced in

Clean Code: A Handbook of Agile Software Craftsmanship

prefer structure over convention

[[§]] Programming your environment

prefer structure over convention