Before you read a codebase, draw its shape

When approaching a new codebase, it's easy to feel overwhelmed by the sheer number of files and the complexity of the project. A small tool called shape.py, written in Python, can provide a helpful overview of the repository in a single screen. This tool prints the file count, total size, source size, non-source weight, top-level layout, and the largest source files. By using shape.py, you can quickly get a sense of the project's structure, entry points, and the distribution of files.

For example, when applied to the OpenAI swarm repository, shape.py revealed that there are only 6 files in the entire framework, making up just 16 KB of the total 962 KB repository. The majority of the codebase consists of examples (236 files, 497.4 KB) and assets (411 KB of images). This distribution highlights that the intimidating size of the repository is primarily due to the various examples and assets rather than the core framework itself.

The tool also highlights the largest source file, tqdm/std.py, which is 56.7 KB in size. This illustrates that a large file does not necessarily indicate poor code quality. In this case, the extensive file size is due to the battle-tested nature of the tqdm library, which contains numerous edge cases and functionalities.

Running shape.py on unfamiliar codebases can help you quickly understand where to start and avoid misclassifications of files as source or non-source. However, it is essential to remember that shape.py provides a structural read of the codebase, not a review of its semantics or a guarantee of bug-free code. It is a valuable tool for gaining an initial understanding of the repository's organization, but it should be used as an aid, not a definitive source of information about the code's quality or functionality.