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、returnVerbatim 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.
- Does the comment explain the WHY?
- Without the comment, would a future worker be likely to mistakenly delete, simplify, or replace it?
- 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.