Better code organization in bazel #

As part of my work on depsaw, I did a lot of investigation into scenarios where we were overbuilding, and the solution for those. Here’s some thoughts on code organization based on that exploration.

More granular packages are better than fewer packages #

The original post has a few scenarios enumerated of why something is overbuilding, but I’ll repeat them here:

Too many files in a single package: this causes the package to change more frequently, but the dependant only needs a couple of the files.
Too much functionality in a single file: there might be a file with thousands of lines of code, but only one function is relevant to a dependent.
Unnecessary dependencies. Where a target has a dependency it doesn’t use at all.

Zooming in one (1) and (2) for a second: I think this points to a more fundamental law about code organization in bazel: that packages should be “many and granular”. Aside from just an incorrect declaration, the other solution to overbuilding is basically “split the package”. Implying that if the dependencies were granular to begin with, we would have preemptively solved overbuilding.

This is also outlined in the bazel best practices:

To use fine-grained dependencies to allow parallelism and incrementality.

A shallow hierarchy is better than a deeper one #

Although tied to the above, but still worth explicitly stating: a shallow hierarchy is better than a deep one. For example,

graph LR
    C --> A
    C --> B
    D --> A
    D --> B
    E --> A
    F --> B

Is better than:

graph LR
    B --> A
    C --> A
    D --> B
    E --> B
    F --> B

A shallow hierarchy:

Helps prevent pulling in functionality from upstream dependencies (better depend-on-what-you-use).
Makes it easier to sever and refactor dependencies (fewer layers to have to navigate through).

Summary #

more packages are better than fewer packages.
granular, composable functionality is better than giant functionality.
a shallow hierarchy of dependencies is better than a deeper one.