notes

notes

This skill is used for writing code comments. By default, comments are written for someone who has just taken over the current module and is not yet familiar with the call chain. Readers should not have to first study the complete implementation and internal terminology in order to understand the comments.

Use it only when the task involves comment governance. Ordinary React, backend, or SQL development tasks should not be triggered merely because these technology stacks appear; if the user asks to check whether the current changes lack necessary comments, it can be used.

Readability check before writing

Each time content is added or updated, all text to be written must first be polished and verified.humanizer-zh When the skill is available, it must be called, and its SKILL.mdmust be fully read and applied. If the current task has already read it and the file has not changed, it can be reused; when it is unavailable, complete the check according to the plain-language rules below and continue writing.

The scope of processing includes all comments, JSDoc, comment conventions, and other explanatory text written this time. First use this skill to determine where comments are needed and what the comments should explain, then polish the draft according to the above rules, verify the meaning, and write it. Do not polish only the final reply or only part of the comments.

Preserve business meaning, conditions, negation, order, and degree of certainty. Code, identifiers, commands, paths, URLs, link targets, structured data, as well as JSDoc tags and type declarations remain as they are; only polish the explanatory text within them. If the text is modified again after writing, the modified part must also undergo the same processing.

humanizer-zh When it is unavailable, use common words and short sentences to explain who is doing what, why it is done this way, and what the result is; explain necessary terminology in plain language, remove empty talk and repetition, and do not add unverified information. Read through from the perspective of a reader who has just taken over the module, and confirm that it can be understood without first studying the complete implementation. Continue to complete the writing, and briefly state in the report that the plain-language rules were used, without claiming that the skill was called.

Specification reading requirements

General comment rules are already written in this file. When performing comment-related tasks, first apply the rules in this file, then read supplementary documents according to the scenario.

• When it involves frontend, React, Hooks, components, event handling, or rendering branches, also read references/frontend.md。
• When it involves Node.js backend, controller, service, SQL, tasks, queues, or external interfaces, also read references/backend.md。

Easy to understand

First use everyday verbs to explain the final effect, then add the reasons that truly affect understanding. Do not cram code prerequisites, internal mechanisms, operation targets, and final results all into one comment.

• Prefer specific expressions such as "find, delete, keep, skip, merge, put before...". Do not stack terminology that only people familiar with the code understand just to appear accurate.
• When technical terms must be used, keep only names that actually exist in the code and cannot be replaced, and put them into complete, short sentences.
• Do not write only surface-level code actions such as "filter data" or "traverse the list"; explain what was deleted or kept, and the necessary reason for doing so.
• After writing, check from the perspective of a newcomer: can someone who did not participate in the implementation understand what happened to the data, what is ultimately left, and why it was done this way? If not, rewrite it.

Too complex:

// 历史状态可能残留同类消息，下游只消费当前阶段追加的最后一项。

Too simple:

// 过滤消息。

Recommended wording:

// 删除旧消息，只保留最新一条，避免重复发送。

Comment decision process

看到一个代码位置
        │
        ├─ 是导出函数或 class static 方法？
        │        └─ 写简短 JSDoc，说明业务用途、关键入参或返回含义
        │
        ├─ 是 for / if 控制流？
        │        └─ 默认在块上方写一行总结，说明业务产出、过滤边界、状态优先级、状态推进或副作用顺序
        │
        ├─ 是同一逻辑阶段里连续定义多个变量，且后面紧跟 for / if 等逻辑处理？
        │        └─ 每个变量上方写 // 描述变量在后续逻辑里的职责，for / if 上方写逻辑块目标、分支边界或优先级
        │
        ├─ 是复杂判断、状态流转、SQL 口径、异步副作用或模型协议边界？
        │        └─ 写注释说明为什么这样做、避免什么误解
        │
        ├─ 是一组相似字段映射或模板取值？
        │        └─ 在这一组上方写一行总结，不逐字段解释
        │
        ├─ 前面有空行，表示进入新的业务小阶段？
        │        └─ 在这一段代码上方写一行组注释；如果说不出注释，就去掉空行
        │
        └─ 是简单赋值、普通取字段、明显空值回退或普通按钮点击？
                 └─ 不写注释

General Judgment Table

Code Scenario	Recommended Action	Comment Focus
Exported functions, static methods of a class	Write JSDoc	Write the business purpose, the business meaning of key input parameters or return results
for / if control flow	Write a group comment by default	Explain the business output, filtering boundaries, state priority, state progression, or side-effect order
Multiple variables prepared, immediately followed by for / if logic processing	Comment each variable	Explain the responsibility of the variables in the subsequent logic; for the logic block, explain the filtering, branch boundaries, or priority
Complex conditions, consecutive conditions, complex ternaries, switch	Write inline comments	Write the basis for the judgment, state priority, or branch boundaries
Numeric calculations, aggregate statistics, field caliber conversion	Write inline comments	Write the calculation caliber, precision boundaries, and final display meaning
Data structure conversion, template concatenation, prompt boundaries	Write inline comments	Write how it is read after conversion, the model-visible boundary, or the user-visible effect
Multiple lines of similar value retrieval or field mapping	Write a one-line group comment	Explain the common semantics of this group of data
Business chunks separated by blank lines	Write a one-line group comment	Explain the business goal of this piece of code in the current flow
Simple assignments, ordinary field access, obvious null fallbacks	Do not write	The code itself already expresses it; do not create noise
"Get so-and-so", "Set so-and-so", "Return so-and-so", "Handle so-and-so"	Do not write	This type of comment only restates the surface behavior of the code

Rule Details

Comments are only written where explanation is worthwhile. They should explain why it is written this way, what misunderstanding to avoid, and what business meaning a field represents. Simple assignments, ordinary field access, obvious null fallbacks, and purely syntactic glue that carries no business meaning should not have separate comments.

If multiple lines of similar value retrieval need explanation, prefer writing a one-line summary comment above this group of code, rather than adding a narration to every line. All for、for...of、for await...of、for...in loops should by default have a one-line group comment above the loop, explaining the business output of this loop iteration, the filtering or normalization boundaries, state progression, and the order of batch side effects; do not write syntactic descriptions like "iterate over so-and-so".if、else if, early returns,continue control flow like this is also by default a complex logic entry point. As long as it is filtering data, determining state priority, protecting business boundaries, switching side-effect order, or changing subsequent output, write a comment above the branch explaining the meaning of the branch; only one-glance null guards, ordinary boolean short-circuits, and syntactic glue with no business meaning may be left uncommented. Blank lines are only used to separate different business stages, different control flows, or explanations that truly need a pause. As long as a blank line is kept, the code block after the blank line must have a one-line group comment above it explaining what this small block is doing; if this section is so simple that no meaningful group comment can be written, remove the blank line and let the code read continuously.

When the same logic stage first defines multiple variables consecutively, and is then immediately followed by for、if、switch When handling logic such as this, you cannot cover the entire block with just one group comment. Above each variable definition, write // ..., explaining the variable's responsibility in the subsequent logic, such as a baseline value, comparison target, accumulation container, state flag, external protocol field, or display convention; above each for / if logic block, write // ..., explaining the filtering, normalization, branch boundaries, priority, or output result that the block is responsible for. Comments still should not explain the syntax itself, nor should they contain surface-level descriptions such as "define variable," "iterate over array," or "check condition."

The focus of these requirements is to provide entry points for reading complex flows. An agent cannot just add JSDoc to exported functions and then skip the internal logic, nor can it assume there is no business complexity just because the code looks short; as long as a loop, branch, or variable group carries business state, filtering conventions, state priority, or side-effect order, this layer of intent must be written out.

Exported functions and static methods of a class must have a brief JSDoc written above their definition, explaining the method's own responsibility and the business meaning of key parameters or return results. Do not write JSDoc that merely restates the function name, and do not bind a general-purpose method to a specific current caller scenario.

Complex conditions, consecutive conditions, complex ternary expressions, switch statements, numeric calculations, field semantics, data structure transformations, display text concatenation, output templates, and prompt boundaries are the places where comments should be added first. Comments should explain the basis for the judgment, the calculation convention, how the transformed result is read, the final user-visible effect, or the model-visible boundary.for / if By default, control flow should have a summary explaining the purpose of the block or the meaning of the branch; exceptions are reserved only for syntactic glue that carries no business meaning at all.

Do not write surface-level comments such as "get so-and-so," "set so-and-so," "return so-and-so," or "handle so-and-so." Do not explain the value retrieval of a dozen fields line by line. Do not write long paragraphs; one comment should cover only one key point.

Example

/** 生成学生在当前课程范围内的课堂表现摘要。 */
export function buildStudentPerformanceSummaries(records: StudentActivityRecord[], activeCourseIds: Set<number>) {
  // studentSummaryById 是学生维度的累计容器，后续循环持续合并同一学生的课堂表现。
  const studentSummaryById = new Map<number, StudentPerformanceSummary>();
  // absentStudentIds 记录已命中缺勤边界的学生，避免后续互动分数把缺勤状态覆盖掉。
  const absentStudentIds = new Set<number>();

  // 逐条过滤课程范围内的课堂记录，并累计学生维度摘要。
  for (const record of records) {
    // 历史课程记录不进入本轮统计口径，避免跨课程表现混入当前摘要。
    if (!activeCourseIds.has(record.courseId)) continue;

    const summary = studentSummaryById.get(record.studentId) ?? createEmptySummary(record.studentId);

    // 缺勤是最高优先级状态，先锁定学生，再跳过互动分累计。
    if (record.status === StudentActivityStatus.Absent) {
      absentStudentIds.add(record.studentId);
      summary.status = StudentPerformanceStatus.Absent;
      studentSummaryById.set(record.studentId, summary);
      continue;
    }

    // 已缺勤学生只保留缺勤状态，不再用后续互动记录回写为活跃。
    if (absentStudentIds.has(record.studentId)) continue;

    summary.answerCount += record.answerCount;
    studentSummaryById.set(record.studentId, summary);
  }

  return [...studentSummaryById.values()];
}

Do not write comments like the following; they only translate the syntax and do not reduce the cost of understanding complex logic.

// 定义学生 Map。
const studentSummaryById = new Map<number, StudentPerformanceSummary>();

// 遍历课堂记录。
for (const record of records) {
  // 判断课程 ID。
  if (!activeCourseIds.has(record.courseId)) continue;
}