File organization

Question: Would moving some members into a separate module (or tests into a separate test file) make the file easier to navigate and maintain?

• Runs: by default · Fails the check by default: no
• Right on projects JevGate was never tuned on: reviews 2 of 5, considers 59% (17 of 29) (how it is measured)
• Right on the projects it was tuned on: reviews 50% (15 of 30), considers 44% (19 of 43)
• Looks at: application and test files with two or more members and 100 or more lines of member code
• Evidence unit: file outline: member signatures and sizes, callers that import the file, and groups; a test file lists its cases with their suites and subjects; no bodies
• Acceptable: One algorithm, one type and its helpers, one feature, or the tests of one subject
• Names: maintainability/file-organization, file-organization, file_organization · Version: 23

When a finding is right

A finding says a file holds parts that would be easier to find in modules of their own, and it names the group of members to move. It is right when the named group is a feature or a job a reader would look for apart from the rest: a URL scraper inside a model, or a diff engine inside a renderer. It is wrong when the file is small and holds one subject, when the named group cuts a feature in half, or when its members cannot move, such as a class’s own methods. About a fifth of the findings labeled wrong or debatable outside Bend 2 code named a group that was no coherent part, and small files about one subject were the next commonest cause.

A file of fewer than 250 lines gets at most a note, a group holding three quarters or more of a file’s members is not named, and a test file’s split is at most a consider.

Findings it got wrong

Labeled wrong by reading the code, on open-source projects the rules were tuned on.

vaultwarden: the mailer

• Where: src/mail.rs:25 in dani-garcia/vaultwarden at 061694d.
• Finding (consider): This file writes out the same kind of code for several features; each feature’s part would be easier to find in its own module. It named two groups: the mail transports with most of the send_* functions, and the template helpers with send_password_hint.
• Why it was wrong: mail.rs is the mailer: one short send_* function per email template, beside the transport and rendering helpers. Neither group is a feature, and splitting the one-function-per-template list across modules would scatter it.
• Since: cleared in 0.21.0: a file that writes out the same kind of code for each of several features is one job (changelog).

httpx: _utils.py

• Where: httpx/_utils.py:162 in encode/httpx at b5addb6.
• Finding (consider): Some members of this file could move to a separate module: URLPattern or the text helpers to_bytes, to_str and unquote.
• Why it was wrong: _utils.py is a 242-line module of small helpers. Moving URLPattern or one-line helpers into modules of their own would scatter a file that is already easy to navigate.
• Since: a note since 0.20.0, which gives a file of fewer than 250 lines at most a note (changelog).

microblog: models.py

• Where: app/models.py:131 in miguelgrinberg/microblog at a975ef6.
• Finding (review): This file holds several features that would be easier to find apart. It named two dozen User methods, or SearchableMixin, as the group to move.
• Why it was wrong: models.py is the application’s one SQLAlchemy models module, 356 lines, whose classes refer to one another. The User methods cannot leave their class; moving SearchableMixin next to the search helpers is optional tidying at this size, not a review.
• Since: not addressed; reported the same way from 0.20.0 through 0.25.0.