Thoughts on Internal Complexity

Complexity is something that needs to be managed down and is an eternal battle. Part of the battle is to stay away from the style and cosmetical changes. Can we really get 100% of style discussions? Even removing discussions of 2–4 tabs, there will be some form of style on the discussion because every engineer has a background towards JEE, Spring, or Functional. That’s a greater generalization, and there are other “design schools” over there but still quite common to find people within these 3 backgrounds. A Philosophy of Software Design is a great book that explains what complexity means. In the book, complexity is mainly described as “Obscurity,” something that is not readable and has a high cognitive load to be understood. IMHO some problem spaces require you to have some background and experience on how some problems are solved; otherwise, it might look the worst they actually are. Complexity discussion often hard since lots of engineers have high EGO and have a hard time decoupling their personal self from their code. That’s why it is important to have a culture of Retrospectives and continuum feedbacks. In this battle is straightforward to throw the towel and give up, but you should not give up.

Obscurity

Obscurity happens because of a lack of continuous improvement culture. Yes, oftentimes, we need to move fast and compromise, but it is possible to keep the code base decently. IMHO a good chunk of the problem is related to the fact that code reviews to shallow and too fast. LGTM happens way too fast, and besides the fact that things can move faster, this might be actually bad in another sense.

The issue with Github code Reviews

Obscurity happens because of a lack of continuous improvement culture. Yes, oftentimes, we need to move fast and compromise, but it is possible to keep the code base decently. IMHO a good chunk of the problem is related to the fact that code reviews to shallow and too fast. LGTM happens way too fast, and besides the fact that things can move faster, this might be actually bad in another sense.

Obscurity Smells

  • When you read the code, you feel something is wrong!
  • Number of moving parts — number of classes
  • Same concern in different packages
  • Annotations, Enums, interfaces, and checked exceptions
  • Abstractions that add little or no value
  • Abstractions that are just delegators

Originally published at http://diego-pacheco.blogspot.com on June 23, 2021.

Brazilian, Software Architect, SWE(Java, Scala, Rust, Go) SOA & DevOps expert, Author. Working with EKS/K8S. diegopacheco.github.io (Opinions on my own)