DEV Community

Cover image for Most React Code Is Hard to Read Because Developers Ignore This One Rule
Samuel Ruiz
Samuel Ruiz

Posted on

Most React Code Is Hard to Read Because Developers Ignore This One Rule

#webdev #javascript #react #programming

Naming is one of the cheapest ways to prevent bugs and mental overhead in React/JS codebases.

Below are practical, opinionated naming conventions that actually matter—with examples that make intent obvious at the call site.

1. Naming Functions

If you need comments to explain what a function does, the name already failed. The naming of a function should tell you what's about without having you read the function definition.

❌ Bad 

getUser()
Enter fullscreen mode Exit fullscreen mode

✅ Good 

fetchUserAPI()      // network
calculateUserAge()  // pure
Enter fullscreen mode Exit fullscreen mode

Why it matters

  • You instantly know what can fail and what can be a synchronous function.

2. Async Functions Must Signal Asynchrony

Rule: Async work should be visible without reading implementation.

❌ Bad 

getOrders()
Enter fullscreen mode Exit fullscreen mode

✅ Good 

getOrdersAsync()
fetchOrdersApi()
loadOrders()
Enter fullscreen mode Exit fullscreen mode

Strong signal hierarchy

  • fetch* → network
  • get* → synchronous access

3. React Components vs Utilities

Rule: Components are nouns. Utilities are verbs.

❌ Bad 

RenderUser
UserHandler
Enter fullscreen mode Exit fullscreen mode

✅ Good 

UserCard        // component
UserList        // component
formatUserName // utility
Enter fullscreen mode Exit fullscreen mode

Bonus

  • Components never start with verbs.
  • Utilities always start with verbs.

4. Event Handlers

Rule: Events describe what happened, not what you’ll do.

❌ Bad 

submit()
click()
Enter fullscreen mode Exit fullscreen mode

✅ Good 

handleSubmit()
handleUserClick()
handleModalClose()
Enter fullscreen mode Exit fullscreen mode

React-specific

  • Always prefix with handle
  • Makes JSX scanning painless

5. Boolean Variables

Rule: Booleans must read like a yes/no question.

❌ Bad 

loading
active
valid
Enter fullscreen mode Exit fullscreen mode

✅ Good 

isLoading
isActive
isValid
hasAccess
canEdit
Enter fullscreen mode Exit fullscreen mode

If it sounds awkward in an if, it’s wrong.

if (isUserAuthenticated) ✅
if (userAuthenticated) ❌
Enter fullscreen mode Exit fullscreen mode

6. State Setters (React)

Rule: Setters must mirror state exactly.

❌ Bad 

const [open, toggleOpen] = useState(false);
Enter fullscreen mode Exit fullscreen mode

✅ Good 

const [isOpen, setIsOpen] = useState(false);
Enter fullscreen mode Exit fullscreen mode

Why

  • Predictable
  • Greppable
  • No surprises for teammates

7. Files That Touch the Outside World

Rule: Files that hit the world should scream.

❌ Bad 

user.ts
utils.ts
helpers.ts
Enter fullscreen mode Exit fullscreen mode

✅ Good 

user.api.ts
user.service.ts
user.mapper.ts
Enter fullscreen mode Exit fullscreen mode

Now you instantly know:

  • .api.ts → network
  • .mapper.ts → transformations

NOTE: You don’t need to specify the file type (user.api.ts) as long as the file is under the ./apis folder.

8. Hooks

Rule: Hooks describe what they provide, not how.

❌ Bad 

useFetchUser()
Enter fullscreen mode Exit fullscreen mode

✅ Better 

useUser()
useAuthenticatedUser()
useUserPermissions()
Enter fullscreen mode Exit fullscreen mode

Let the hook hide implementation details.

Mental Model Summary

Good naming answers these without reading code:

Question Naming Signal
Hits the network? Async? fetch, .api.ts, fetch, load, Async
Mutates state? set, mutate, append
Pure logic? calculate, format
UI component? PascalCase noun
Boolean? is, has, can

Top comments (0)