SuperAPI AI Directory

kf-g-code-comment-why-only

General & other

View repository

Updated 10-15 21:02

About this skill

Code Comment Guidelines

Use this skill when adding, editing, reviewing, or deciding whether to delete source code comments in this repository.

Basic Policy

In-code comments must always state only the WHY. Assume the WHAT can be read from the code.

Treat comments as a means of passing on to future workers context that cannot be read from the code alone. If an explanation of what the processing does seems necessary, first prioritize seeing whether readability can be improved through naming, function decomposition, types, or tests.

Content That May Be Commented

Leave as comments only reasons and background that cannot be read from the code, such as the following.

  • Why that library, API, or dependency was chosen
  • Why an alternative implementation that looks simpler was avoided
  • Why this order, conditional branch, wait, retry, or fallback is necessary
  • Why compatibility, performance, security, or operational constraints are being prioritized
  • Why it is adapted to the quirks of external services, browsers, Docker, file formats, etc.
  • Why processing that appears unnecessary at first glance is being kept
  • The rationale for decisions made to avoid past defects or regressions

Content Not to Comment

Do not write explanations of the WHAT, such as the following. If any already exist, delete them or replace them with WHY within the scope of surrounding changes.

  • Explanations of processing that are understood by reading function names, variable names, types, or control structures
  • if、map、filter、return Verbatim explanations such as
  • Explanations at the same granularity as the code, such as "convert the image" or "return the response"
  • Comments that merely need to be kept in sync with the implementation
  • Vague wishes in the form of TODOs, or notes whose author's intent is unclear

Decision Procedure

Before adding or keeping a comment, check the following.

  1. Does the comment explain the WHY?
  2. Without the comment, would a future worker be likely to mistakenly delete, simplify, or replace it?
  3. Would it be more natural to improve the naming or structure of the code?

If the first is not satisfied, do not write the comment. If the third is natural, prioritize improving the code over commenting.

Examples

Avoid:

// 画像を JPEG に変換する
const converted = await convertToJpeg(image);

Good:

// HEIC はブラウザ表示が不安定なため、プロキシ側で JPEG に寄せて返す。
const converted = await convertToJpeg(image);

Avoid:

// アセット ID がなければ 400 を返す
if (!assetId) {
  return error(400, "assetId is required");
}

Good:

// Immich API への空 ID 転送は 500 として返るため、利用者向けにはここで入力エラーに正規化する。
if (!assetId) {
  return error(400, "assetId is required");
}

Handling During Review

In code review, when you find a WHAT comment, treat it as a deletion candidate. If a WHY is necessary but there is no comment, check not only whether to add a comment but also whether a clearer name or structure could be used.