03.08.2023 **Tags** #areas/dev/software-design # Deep Modules The idea of deep modules is, that they should generally hide a larger portion of implementation code behind a short interface. An example of this is the UNIX I/O API, which exposes 5 functions: `open`, `read`, `write`, `lseek` and `close`, which hide hundreds of thousands of lines of implementation code behind a handful of simple functions, none of them having more than 3 arguments. - in short: **simple interface, powerful implementation** On the other hand, shallow modules are modules that don't hide a lot of implementation and add up to the complexity of the system, while not providing a lot of functionality. - in short: **complex interface, weak implementation** ## Personal Opinion My first thought was that, Interestingly, this is one of the (multiple) times where a heuristic from this book clashes with a heuristic from another, quite popular philosophy: Clean Code. Clean Code emphasizes (really) short functions with expressive names, which automatically makes them shallow by the definition of Ousterhout. I have to admit, I also took the Clean Code approach to the extreme. A very good example is this tiny (<100 lines of code) Telegram Bot, which parses a JSON response from an HTTP API, formats the information in a pleasant way and responds to the chat with the result: https://github.com/ReinhardtJ/PyFLTS3Bot/blob/main/main.py While this mini-project was just for fun and playing around with some patterns from functional programming, the result is a program that is difficult to decipher. If this was just one function instead of 10, and implemented in a pythonic way, it would be 5 times less complex. But I also do have problems with functions that start to get nested deeply and require me to scroll up and down a lot (or even worse: left to right). When designing functions, I would try to use common sense and achieve the heuristic of functions that "do one thing only" without cluttering the codebase with one- or few-liners which make the program flow difficult to reconstruct mentally. When it comes to classes, I would definitely focus on getting the interface right. Even if the class becomes a bit shallow. But if the class becomes deep *and* keeps a simple interface, even better. In conclusion, I agree with Ousterhout with some constraints. # References [[A Philosophy of Software Design (John Ousterhout)]]