Overview

Every comment should earn its place. A good comment provides context the code alone cannot convey — why a decision was made, what trade-off was accepted, or how a non-obvious piece fits the bigger picture. A comment that merely restates the code is noise; remove or avoid it. When in doubt, prefer no comment over a redundant one.

Guidelines

• Comment only when needed. Do not add comments or JSDoc unless the code is non-obvious or you are explicitly asked. Self-explanatory code needs no narration.
• Inline comments: ≤ 2 lines. Keep them terse — explain why, not what.
• JSDoc: comprehensive yet concise. Document only what adds value: purpose, non-obvious parameters, return semantics, or usage examples. Omit what the signature already communicates.
• Use /** ... */ for reusable symbols. Functions, types, and constants referenced elsewhere should use JSDoc so IDE hover tooltips display the information.
• Document trade-offs. When the implementation accepts a trade-off, explain the rationale and why it was worth taking.
• No assumptions. Ground comments in library docs, project standards, or best practices — not guesses. Ask for clarification when unsure.
• Stay consistent; never contradict. Match the tone and terminology of existing comments. Do not duplicate information already stated in a nearby comment — reference it instead.

Example

The annotated snippet below highlights common comment pitfalls alongside good practice.

// (1) Calculate chart segments based on priority: verified > registered > rejected
const getChartSegments = (): {
  value: number
  color: string
  backgroundColor?: string
  badgeLabel?: string
}[] => {
  const verified = data?.verified ?? 0
  const registered = data?.registered ?? 0
  const rejected = data?.rejected ?? 0
  const total = verified + registered + rejected

  // (2) If all values are 0, show full gray circle
  if (total === 0) {
    return [{ value: 1, color: colors.palette.lightGray }]
  }

  // (3) Filter out zero values to prevent empty segments
  const segments = []

  // (4) Priority order: verified > registered > rejected
  if (verified > 0) {
    segments.push({
      value: verified,
      color: '#01C58A',
      backgroundColor: '#D6F6EC',
      badgeLabel: `${verified} Aset Terdata`,
    })
  }
  if (registered > 0) {
    segments.push({
      value: registered,
      color: '#FF9E00',
      backgroundColor: '#FFF1DB',
      badgeLabel: `${registered} Belum Diverif`,
    })
  }
  if (rejected > 0) {
    segments.push({
      value: rejected <= 2 ? 2 : rejected, // (5) Minimum visible segment size of 2
      color: '#FF5264',
      backgroundColor: '#FFECEC',
      badgeLabel: `${rejected} Ditolak`,
    })
  }