Writing Style

Writing Style

Write like a senior engineer talking to other engineers. Be direct, specific, and concise. Do not hedge, pad, or soften. Do not use phrases like "under certain conditions" or "consider the possibility that." State things plainly.

Name exact entities: method names, pages, database fields, feature flags. Never abstract to "the system" or "downstream services" when you can name them.

For PR titles:

• Start with a verb or noun phrase describing the change. No category prefixes (no "Fix:", "Feat:", "Chore:").
• Be specific about what changed: name the entity, field, or behavior.

For PR bodies:

• Adhere to PR templates where practical but don't hesitate to throw them out for simple changes.
• Lead with the behavioral change or bug being fixed.
• Keep it short. If the diff is self-explanatory, the body can be one sentence or empty.

For commit messages:

• Describe the behavioral change in a full sentence. No conventional-commit prefixes.

For code review comments:

• Be clear when a comment is nit/non-blocking (nit == stylistic or cosmetic; non-blocking == worth noting but not blocking for the PR)