Mahdaad Dev Handbook

Appearance

Coding Guidelines ​

Introduction ​

This guide includes coding standards and best practices for the project.

General Principles ​

Code Readability ​

  • Code should be readable and understandable
  • Use meaningful names
  • Add appropriate comments

Consistency ​

  • Follow a consistent coding style
  • Use linting tools
  • Review code before committing

Performance ​

  • Write optimized code
  • Use appropriate patterns
  • Test performance

JavaScript/TypeScript Standards ​

Naming ​

  • camelCase for variables and functions
  • PascalCase for classes and components
  • UPPER_SNAKE_CASE for constants

Code Structure ​

  • Use const and let instead of var
  • Use arrow functions
  • Use destructuring

Commenting ​

  • Avoid unnecessary comments; code should be self-explanatory whenever possible.
  • Only comment in these cases:
    • JSDoc for functions, classes, modules, and public APIs.
    • A single-line comment that starts with one of the standard tags below.
TagUsage
TODO:Something to do later
FIXME:There is a bug that must be fixed
BUG:Indicates this part of code is buggy
HACK:Temporary or non-standard workaround
NOTE:Important explanation about code behavior
REFACTOR:Needs restructuring or cleanup
OPTIMIZE:Needs performance optimization
REVIEW:Needs review/approval by a teammate
DEPRECATED:Code to be removed or has a replacement
SECURITY:Highlights an important security concern
DEBUG:Debug-only or temporary investigation code
WIP:Work in progress

Additional rules:

  • Tags must be uppercase, followed by a colon and a single space; keep messages short, clear, and actionable.
  • Placement: directly above the related line/block or inline on the same line, not scattered elsewhere.
  • JSDoc should be used only for externally used APIs or non-obvious logic.
  • Commented-out code is prohibited; remove it if not needed. If temporarily required, explain why and when it will be removed.
  • Remove WIP: and DEBUG: before opening a PR.
  • For SECURITY:, be precise and unambiguous; ideally include a link to the ticket.

Examples:

ts
// NOTE: move issue
// TODO: migrate to new payment gateway before Q4 release
// FIXME: handle null userId when session expires

/**
 * Check if a line contains one of the predefined TAGS
 * Returns the matched tag or null when none is found.
 */
export function detectCommentTag(line: string): string | null {
  const tags = [
    'TODO:', 'FIXME:', 'BUG:', 'HACK:', 'NOTE:', 'REFACTOR:',
    'OPTIMIZE:', 'REVIEW:', 'DEPRECATED:', 'SECURITY:', 'DEBUG:', 'WIP:'
  ];
  const found = tags.find(tag => line.trimStart().startsWith(`// ${tag}`));
  return found ?? null;
}

Prohibited:

  • Restating the obvious (e.g., “increment i” next to i++).
  • Humor/sarcasm, personal remarks, or inappropriate language.
  • Recording history in comments; use VCS for that.
  • Overly long explanations; use README/ADR or link the ticket instead.

CSS/SCSS Standards ​

Class Naming ​

  • Use BEM methodology
  • Meaningful and short names
  • Avoid generic names

Structure ​

  • Use CSS variables
  • Logical grouping of rules
  • Use appropriate nesting

Code Quality Tools ​

Linting ​

  • ESLint for JavaScript/TypeScript
  • Stylelint for CSS/SCSS
  • Prettier for formatting

Testing ​

  • Jest for unit testing
  • Cypress for e2e testing
  • High coverage (minimum 80%)

Best Practices ​

Security ​

  • Validate inputs
  • Use HTTPS
  • Protect against XSS and CSRF

Accessibility ​

  • Use semantic HTML
  • Support screen readers
  • Follow WCAG guidelines