Embedded Files
This page defines the core principles, conventions, and standards to ensure consistency, quality, and maintainability across all projects in our organization.
Core Principles
Core Principles
Clean code: Code must be readable and explain itself without comments, if you need to write a comment, the code is probably unclear.
Consistency: Follow the same patterns everywhere.
Simplicity: ALWAYS prefer the simplest solution that works. Avoid complex abstractions, clever hacks, or over-engineering.
(This includes premature optimization - e.g. in React, things like memoization or useCallback should only be used when there's a real, measured performance issue)
Single responsibility: Each function, class, or component should do exactly one thing and do it well. Aim to keep files under ~40 lines.
Maintainability > Speed: Write code you (and others) can come back to in 6 months without pain. Quick hacks rot fast.
Files & folders
Files & folders
Goal: Keep the project organized so any dev can jump in, understand the structure, and find what they need without guessing.
1. Recommended structure
2. Principles
Feature-based organization
Each feature owns its own components, services, and hooks.
Avoid dumping all components in a shared folder unless they’re truly reusable
Example:
Shared code
Shared code
Shared folder is only for code used by multiple features.Reusable UI, utilities, hooks, or provider setups go here.
Example:
File naming
Files & folders: kebab-case (user-route.js, auth/, dashboard/)
Components: PascalCase (UserProfile, AnswerList)
Variables/functions: camelCase (getUserData, getShops)
Constants: UPPER_SNAKE_CASE (API_BASE_URL, MAX_RETRIES)
File size
File size
A small file isn’t just easier to read. It’s easier to test, easier to replace, and much simpler to delete when it becomes obsolete.
Functions/Components: max ~40 lines
Any file > 100 lines? split it!
Styling and UI rules
Goal: Maintain a consistent visual language, reduce “one-off” styling, and make UI easy to maintain and scale.
1. Use shared UI components first
Always build with src/shared/ui components.
Only create custom components if absolutely necessary.
Example:
2. Avoid one-off custom styles
Styles should live in the theme or shared style files.
Inline styles or repeated magic numbers = maintenance nightmare.
Example:
3. Text capitalization & consistency
Sentence case only: “Sign up”, “Enter your email”.
Avoid Caps Per Word or inconsistent casing.
Example:
Final note
These are not suggestions. These are rules.
Breaking them without a clear reason = adding friction to the team.
Consistency compounds. If every developer respects these guidelines, our codebase stays clean, scalable, and enjoyable to work with.
Most of these principles were drilled into me by Abel (our CEO), and the rest I learned the hard way by building, breaking, and fixing code myself. They’re written here so nobody on this team has to relearn them the painful way.
Let’s keep the bar high.
– tsu (Luca Di Marco)
Page updated
Report abuse