jungho-git/comments

Comments

• Shared examples and formatting reference: references/EXAMPLE.md.
• Keep new guidance, snippets, and edits aligned with that file.

---

Scope

Use this rule when:

• adding or editing comments in code
• adding or changing a function, class, method, script section, SQL block, or logical phase
• preserving or extending an existing section-comment scaffold
• deciding whether a comment is needed

Comments should improve scanability and preserve flow. They should not become decorative churn.

---

Core Rules

• Add a numbered section-divider comment above each new or materially changed function, class, method, or major logical section when the file supports line comments.
• Do not sweep untouched declarations just to normalize comments.
• Preserve existing local comment rhythm unless it conflicts with the requested change or this skill's hard rules.
• Prefer one-line numbered dividers for normal sections.
• Use paired outer divider blocks only for very long regions or major file sections.
• Keep comments structural, concise, and purpose-driven.
• Do not add comments that restate obvious syntax.
• Do not split code only to create comment boundaries.
• Do not rename or translate existing comments unless they are incorrect or the user requested it.

---

Divider Style

• Use the file's local single-line comment prefix such as //, #, --, or ;.
• Use repeated ―, not -, for ruler characters.
• The rendered divider line should be 100 characters, including indentation, prefix, title, one space before the ruler, and repeated ―.
• Shorten long titles before exceeding the 100-character line.
• Use top-level numbers such as 1. and child numbers such as 1-1..
• Keep numbering depth to two levels.
• Renumber only the local touched scaffold when needed for consistency.
• Do not create long child chains such as 1-10.; split broad sections instead.

---

Placement

• Place the divider immediately above the declaration or logical block it describes.
• Keep exactly one empty line above a divider when it follows code or prose.
• Do not leave two or more empty lines above a divider.
• Do not insert an empty line inside a paired three-line divider block.
• Start code on the next line after a one-line divider or paired divider block.
• Allow one empty line after a top-level divider when it introduces child sections.

---

Comment Content

• Name the purpose, business meaning, boundary condition, grouping intent, editability rule, or non-obvious constraint.
• Prefer compact noun-like Korean comments when writing Korean in files that already use compact Korean comments.
• Use a plain internal comment only when one local line explains a non-obvious operation better than a section divider.
• Keep generated, copied, or externally synchronized blocks marked when editability is restricted.

---

Add Or Skip

• Add a comment when the user asks for comments.
• Add a divider for new or materially changed declarations and major logical phases.
• Add a comment when the business rule or boundary is not obvious from names and types.
• Skip comments for tiny obvious constants, assignments, imports, simple property mappings, and unchanged code.
• Prefer no comment over a vague or fabricated comment.

---

Boundaries

• Do not comment every line mechanically.
• Do not let comment policy widen the code change.
• Do not fabricate intent that is not supported by the code.
• Do not override language-specific documentation requirements such as public API Javadocs when they are required.
• Do not use this skill as permission for broad formatting or repository-wide comment normalization.