The Quiet Design Choices Behind a 50-Line CLI Tool

This article discusses the design choices made while building a CLI tool that organizes files by type within a directory. The author highlights three key design decisions and their underlying rationale.

Firstly, the author opted for the pathlib module over os.path. The reason is that paths should not be treated as strings, as this can lead to bugs. Using os.path, extension logic requires manual implementation, which can become problematic with compound extensions like archive.tar.gz. In contrast, pathlib provides a clear and explicit way to handle paths, allowing developers to choose between the last suffix (suffix) or all suffixes (suffixes).

However, even pathlib does not fully prevent compound extensions from being misclassified. The author emphasizes that pathlib does not eliminate the issue, but it does provide a typed, documented approach to selecting the desired behavior.

Secondly, the author implements a dry-run feature before executing any file-moving operations. This feature is essential because moving files is not a straightforward process and cannot be easily undone. While performing a dry-run may seem trivial on a personal machine with well-understood files, it becomes crucial when files are shared across various systems or are irreplaceable.

The dry-run flag is designed to be non-invasive, allowing users to preview the operation with minimal effort. The dry-run flag does not alter the underlying logic; it simply changes the final step from executing the move to displaying the destination directory. Both modes share the same logic and output structure, differing only in the last step.

Lastly, the author avoids using if/elif chains for file classification and instead employs a dictionary mapping. If/elif chains combine data and logic, making it difficult to add new file types without modifying the function's control flow. This approach increases the risk of breaking existing, already-tested branches. In contrast, using a dictionary separates data and logic, allowing new file types to be added with minimal effort.

The EXTENSION_MAP dictionary maps file extensions to their respective directories, and the lookup operation remains consistent, regardless of the number of file types. This approach not only improves code readability but also allows the mapping to be easily edited by non-programmers in a separate configuration file, such as a config.json.