One Function per File

[karlrwjohnson]

One rule I started using on my team (and got positive feedback on) is "only define one (public) function per file".

This is mainly applicable to "utility" function files.

In my experience with Java, tons projects are littered with "utility classes" that group similar functionality, e.g. StringUtils, DateUtils, and the like. These files run into a couple of problems:

1. How do you sort functions in these files? Alphabetically? Dependency order? If someone added their function at the end of the file while you were out on vacation, do you want to break the commit history to move the function where it needs to go?
2. What happens when they get too big? Do you start splitting out files like "StringCasingUtils" and "StringFormattingUtils"?
3. What if a function could go into one file or another? Does your special proprietary date-formatting function belong with strings or dates?

(I pick on Java because the fact it forces you to use classes seems to encourage people grouping functions together unnecessarily.)

All of these are solved by putting each function in its own file. Filesystems don't care about sort order, and Git doesn't think a file "changed" if you move it into a child folder.

Obviously this isn't a hard-and-fast rule. For example, "helper" functions that are only called by one other function can stay in the same file -- they're never exported anyways.

There's a side benefit in that in Typescript, your function is sometimes accompanied by type definitions or constants. When there's only one function in the file, it's obvious what those typedefs and constants belong to. If your file is littered with a bunch of other functions that are only incidentally related, it gets harder to track what's going on.

[mkosir]

Hi @karlrwjohnson 👋 , thanks for nice write up, I'm basically following similar approach in projects!
I know there are some strong opinions on multiple vs single components/functions per file, which comes down to team agreement, but I really like your take and strongly agreeing with it, especially when it comes to utility functions!
It would be nice if you could make contribution to the guide on this convention with brief "why" explanation on it!