Code Comments

Field Details
Status Active
Last Updated 05-11-2026

Purpose

To maintain clean, self-documenting code with minimal but meaningful comments

Scope

Applies to: All codebases (backend, frontend, mobile)

Does not apply to: Auto-generated code, third-party libraries

Golden Rule

Write self-descriptive code first. Comment only when necessary.

Code should explain itself through: - Clear function and variable names - Simple, logical structure - Small, focused functions

Add comments only when code cannot explain the "why".

When to Comment

Do Comment

  • Complex business logic that isn't obvious
  • Why you chose a specific approach
  • Workarounds for bugs or API limitations
  • TODOs with ticket references

Don't Comment

  • What the code does (if it's clear)
  • Obvious operations
  • Every line of code
  • Getter/setter functions

Comment Style

Keep It Short

// Good: Explains WHY
// Retry 3 times - external API is unstable
const maxRetries = 3;

// Bad: States the obvious
// Set max retries to 3
const maxRetries = 3;

One Line Maximum

// Good: Brief and clear
// Skip weekends for business days calculation

// Bad: Too verbose
// This section of code handles the calculation of business days
// by excluding weekends from the total count. It iterates through
// each day and checks if it falls on a weekend...

Self-Documenting Code

Instead of Comments, Use Better Names

// Bad: Needs comment
// Check if user can access premium features
if (u.t === 2 && u.exp > Date.now()) { }

// Good: No comment needed
function hasActivePremiumAccess(user) {
  return user.tier === PREMIUM && user.expiryDate > Date.now();
}

Extract Complex Logic

// Bad: Comment explains complex condition
// Check if order is eligible for discount
if (order.total > 100 && customer.orders > 5 && !order.discounted) { }

// Good: Self-explanatory
if (isEligibleForLoyaltyDiscount(order, customer)) { }

TODOs

Format: // TODO: [TICKET-123] Brief description

// TODO: [API-456] Remove after payment service v2 migration
// TODO: [BUG-789] Handle edge case for null values
  • Always include ticket number
  • Keep under 10 words
  • Remove after completion

Common Mistakes

Commented-Out Code

// Bad: Don't keep dead code
// const oldLogic = () => { 
//   return data.filter(...)
// }

Delete it. Use Git to recover if needed.

Noise Comments

// Bad: Adds no value
////////////////
// Constructor //
////////////////
constructor() { }

Exceptions

Documentation generation tools (JSDoc, Swagger) may require verbose comments - that's acceptable

Changelog

Version Date Author Change
1.0.0 05-11-2026 Tibin Sunny Initial version