Essential Coding Etiquettes for Developers

Code is more than instructions for a machine — it’s a conversation with other developers. Every line you write is read dozens, maybe hundreds, of times by teammates and your future self. That’s why coding etiquette matters: it’s not about being “perfect,” it’s about being considerate. When you follow good etiquette, you make life easier for everyone who touches the codebase.

Here’s a practical set of coding etiquettes, explained in a way that’s easy to remember — like conversations, not commandments.

---

Make Code a Conversation, Not a Puzzle

Write code that feels like a dialogue. Clear names and simple flow mean no one has to solve riddles just to understand your work.

• Names reveal intent. A method name should tell what it does, not how.
• Use domain language. Align names with your business/domain, not technical jargon.
• Make names memorable. Searchable, pronounceable, and precise — easy to recall, discuss, and maintain.
• Avoid ambiguity. Skip vague names like data, info, or manager when more descriptive ones exist.

Keep Functions & Classes Conversational

• Functions should do one thing well.
• Use clear parameters: prefer userId: string over a vague id.
• Avoid long argument lists — group related data into an object.

Write Code Like a Story

• Arrange code so it reads top-to-bottom naturally.
• Use early returns instead of deep nesting.
• Extract complex logic into helpers so the main flow stays obvious.

Comments Should Answer “Why,” Not “What”

Good code already shows what it does. Comments should explain why you did something — especially when your choice isn’t obvious.

• Explain decisions: Why this algorithm and not another? Why hardcode this value?
• Give context: Link to a ticket, doc, or standard if it influenced the code.
• Point out trade-offs: Sometimes you choose speed over readability or vice versa. Say so.
• Mark work to revisit: Use clear TODOs with details, like // TODO: update tax rules in 2025.

Keep Functions Small, Like Focused Notes

Each function should play one clear note, not the whole orchestra. Short, single-purpose functions are easier to read, test, and reuse.

• Do one job per function.
• Smaller is safer: easier to debug, easier to test, and easier to reuse later.
• Use clear inputs: userId makes sense, id doesn’t.
• If you need 7 parameters, maybe you actually need a small object.

Leave the Codebase Cleaner Than You Found It

The “Boy Scout Rule” comes from an old idea in the Boy Scouts of America handbook:

“Always leave the campground cleaner than you found it.”

Robert C. Martin (a.k.a. Uncle Bob, author of Clean Code) borrowed this saying for software.
His point was: every time you work on code, don’t just finish your task — tidy up a little too.

• Rename a confusing variable.
• Delete unused code that’s been lying around.
• Fix formatting or indentation.
• Add a missing comment or test.

You don’t have to do a massive cleanup — just leave things a bit better than they were. Over time, all those tiny improvements keep the codebase healthy.

Errors Should Explain, Not Confuse

Don’t leave future developers guessing. Write meaningful error messages and logs so problems are easier to track down.

• Bad error messages are like “404” without context. Good ones guide you.
• Say what failed and how to fix it.
• Log technical details for devs, show simple hints to users.

Follow the House Rules

Every team has its own “style guide.” Follow it — even if you’d do it differently.
Consistency across the project matters more than personal preference.

• Stick to the agreed naming style
• Use the same folder and file structure
• Follow shared formatting and linting rules
• Respect conventions already in place
• Document exceptions instead of making silent changes

Think of it like a school dress code — it may not be your favorite style, but it keeps things simple for everyone.

Commit Messages Tell the Story

Commits are like diary entries for your project. Future you (or your teammate) should be able to read them and instantly understand what changed and why.

• Be clear 'why you are pushing this commit'
• Use present tense
• Explain the why if the change isn’t obvious
• One commit, one purpose
• Keep commits small so they’re easier to review and debug
• Follow a convention (like Conventional Commits)