Naming conventions are the part of a codebase nobody writes down and everybody can feel. I went looking for Nakodo's, by counting rather than by remembering, because the rules I think we follow and the rules the files actually follow are two different lists.
A warning about method before the numbers: a regex census of identifiers is wrong at the edges. It cannot see a name produced by destructuring, it counts a declaration not a use, and it will read charAt as one of ours. Every number below is a count of declarations matched by a pattern, and I have said which pattern where it matters.
Files and folders
583 TypeScript, TSX and CSS files under src, in 100 directories.
| File name style | Count |
|---|---|
single word, lower case (actions.ts, nav.tsx) |
475 |
kebab-case (not-found.tsx, results-view.tsx) |
108 |
| PascalCase | 0 |
| camelCase | 0 |
| snake_case | 0 |
The most repeated names are the framework's: page.tsx 53 times, route.ts 19, loading.tsx 19, index.ts 12, actions.ts 10, layout.tsx 7. Directories are the same shape: 79 single words, 7 kebab, plus six route groups in brackets ((app), (auth), (marketing), (list), (results), (profile)) and eight dynamic segments ([id], [slug], [token], [...path] and four more).
The React convention of naming a file after its component does not exist here at all. 155 files export a PascalCase function; here is what their names do:
53 file name is the component, kebab-cased results-view.tsx -> ResultsView
42 file name belongs to the framework page.tsx -> HowItWorksPage
27 component name ends with the file name nav.tsx -> MainNav, SettingsNav
34 file holds a group, named for the group forms.tsx -> ChangePasswordForm, widgets.tsx -> calculators
widgets.tsx is the clearest case: one file exporting four components, one of which is InstagramEngagementRateCalculator, our longest identifier at 33 characters, which you can go and use on the Instagram engagement rate calculator.
Three files are called nav.tsx and none of them is ambiguous, because the folder above says which navigation it is. That is the actual rule: a file is named for the job it does in its folder, and the component is named for what it is in the whole app. It works, it is undocumented, and the only cost is that a global search for MainNav finds the component and never the file.
Declarations
function declarations 1,530 camelCase 998 PascalCase 471 SCREAMING_SNAKE 2
const declarations 4,461 camelCase 1,512 SCREAMING_SNAKE 515 PascalCase 22
type declarations 360 PascalCase 337 distinct names, nothing else
Not one type alias in the codebase is named in anything but PascalCase, which is unsurprising. The two SCREAMING_SNAKE functions are the surprise, and both are deliberate: they are table-shaped constants that happen to be callable.
The thing I expected to find and did not is verb-first function naming. Of the 998 camelCase functions, only 325 (33%) start with a verb from a generous list of 60. The rest are noun phrases: accountOf, appUrl, addressFoundAt, answerAsBrand, allowedByRobots, amountsIn. Reading them back, the pattern is consistent even though nobody chose it: a function that performs an effect is a verb (sendEmail, queueRun, saveBrief), and a function that computes a value is named after the value it returns, so the call site reads like a field access. plan.amountsIn(currency) says what you get. getAmountsIn would say what the computer does.
Boolean names are the shortest convention in the codebase:
is… 63 names isActive, isDisposableEmail, isAdminEmail
has… 17 names hasCard, hasEmail, hasBrief
can… 3 names canLaunch, canNegotiate, canReply
should… 1 name shouldEnableManagedPayments
did… 1 name didWork
will… 0
Acronyms are words, except where they are constants
| Spelling | Names | Examples |
|---|---|---|
Url |
36 |
absoluteUrl, cardUrl, channelUrl
|
URL |
11 | all SCREAMING constants: SITE_URL, DATABASE_URL
|
Id |
48 |
campaignId, PlanId
|
ID |
0 | |
Html |
9 |
escapeHtml, ParsedHtml
|
HTML |
10 | all of them from the DOM lib: HTMLButtonElement
|
So the rule, which nobody wrote down, is: inside an identifier an acronym is a capitalised word, and the only all-caps spellings are inside SCREAMING_SNAKE constants where every letter is capital anyway. ID appears zero times in our own code. That is the sort of consistency you only get by accident or by review, and I am fairly sure it was accident.
The suffix that has five exceptions
Server Actions get an Action suffix. Counting the exports of every file with "use server" in it:
exported server actions: 62
ending in "Action": 57
not: signIn, signUp, resendConfirmation, requestPasswordReset, resetPassword
All five exceptions are in one file, (auth)/actions.ts, and they are the five oldest actions in the project: they were written before there were enough of them to want a suffix. There is nothing wrong with them, and renaming them touches five forms, so they have stayed. This is what a convention looks like from the inside: a rule with a dated exception, where the date is the thing that explains it.
The suffix earns its place in JSX, where action={saveBriefAction} tells you a network call happens on submit and action={saveBrief} does not.
The database spells its names twice, in one word
25 tables, 23 of them plural. The two that are not are provider_state and audit_log, which are a state and a log, and neither pluralises without sounding wrong.
The column names are the interesting part. Searching the ten drizzle constructors the schema imports finds 294 column declarations, and 292 of them I can read a name from:
columns with a capital letter in the TS name: 155
columns that are a single lower-case word: 137
columns whose declaration spells the SQL name: 0
Not one. No text("created_at") anywhere. The mapping is one option, written twice:
// drizzle.config.ts
casing: "snake_case",
// src/db/index.ts
export const db = drizzle({ client, schema, casing: "snake_case" });
One for the migration generator, one for the query builder, and the code never writes a snake_case string at all. The risk is obvious once you see the two lines: they are the same decision in two files, and if they ever disagree the generated SQL and the runtime queries disagree about every camelCase column at once. It has never happened, and the only reason it has never happened is that nobody has had a reason to touch either line.
Column suffixes, as a measure of what this schema is for:
…At 45 timestamps
…Id 30 references
…Count 7
…Reason 5
…Url 4
45 of 292 columns record when something happened. The public shape of that is how it works, which is mostly a description of things that happen on a schedule. A schema that stores times rather than flags was a deliberate choice, and the suffix count is the cheapest way to see it from outside.
What I am changing
- Write the file naming rule down, because "named for its job in its folder" is a real rule that a new contributor cannot infer from
nav.tsxalone. - Pull
casing: "snake_case"into one exported constant that both drizzle entry points import, so the two lines cannot drift. - Leave the five unsuffixed auth actions alone, and note in the file why they are different, since the current state reads as an oversight and is actually a cost decision.
- Nothing about verb-first functions. Measuring it taught me that the split is between effects and values, and that is a better rule than the one I would have imposed.
Top comments (0)