SuperAPI AI Directory

comment-code

General & other

View repository

Updated 10-15 21:40

About this skill

comment-code

Add or reinforce comments and documentation comments in code. The purpose is to describe, in a form that can be read on the spot, the boundaries of responsibilities, the assumptions of callers, the contract of return values, and dependencies on other places, without changing the code implementation.

Usage

comment-code <対象ファイルまたはディレクトリ> [--lang <言語>]

If the argument is omitted, git diff HEAD the diff files of are targeted. --lang When specified, the documentation comment format (JSDoc / docstring / rustdoc, etc.) is treated as the preferred language. If not specified, it is automatically determined from the extension.

Prerequisites

  • The target file must be readable
  • Must be inside a Git repository (because git diff HEAD is used when the argument is omitted)

Flow

Step 1: Identify the target file

If an argument is specified, target that file or directory.

# 引数なしの場合: 直近の差分ファイルを列挙(staged / unstaged 両方を HEAD と比較)
git diff HEAD --name-only
# untracked(新規未追跡)ファイルも対象にしたい場合
git ls-files --others --exclude-standard

If the target is empty (no changes, no argument), confirm the target with the user.

Step 2: Investigate the target's role from the codebase

This step is the most important. Rather than looking only at a single file, understand its position within the entire system.

2-1: Investigate callers

Search the entire codebase for symbols exposed by the target file (functions, classes, types, constants), and understand which layer or service calls them.

# シンボル名で呼び出し元を検索(例: exportされる関数名)
grep -rn "対象シンボル名" --include="*.ts" --include="*.js" .

2-2: Check imports and dependencies

Understand the external modules, services, and configurations that the target file depends on.

# import 文の一覧
grep -n "^import\|^from\|require(" 対象ファイル

2-3: Check package and service boundaries

  • package.json・go.mod・Cargo.toml Check the package name and public API with etc.
  • If inter-service communication (HTTP clients, event publishing, message queues) is included, identify the connection destination
  • Check the relationship between authentication/authorization middleware and session management and the target

2-4: Check the existing comment style

Read existing comments in the same file and same package, and understand the style (JSDoc / docstring / rustdoc, etc.) and language (Japanese/English).

Step 3: Add or reinforce comments

Write the perspectives from other files and other services understood in Step 2 as comments.

Comment style conventions (core idea)

If .claude/rules/code-comment-style.md exists in the target repository, follow it preferentially. If it does not exist, follow the points below.

What to write:

Perspective What to write
Boundaries of roles and responsibilities "This module is responsible for the ~ boundary of the ~ service" / "It functions as the public interface of the ~ package"
Context of the caller Which layer or which service calls it. The state and permissions the caller assumes
Contract with the callee What it guarantees and returns. The conditions for errors and exceptions and their meaning (whether it returns null or throws an exception, etc.)
Dependencies on other files and other services External dependencies, configuration, and shared state that a reader cannot find without crossing files
Non-obvious constraints, background, and why Why the implementation is the way it is. Background, constraints, contracts, and specification limitations

What not to write:

  • Verbatim explanations that are obvious from the signature or types (restating the what)
  • Duplicated information that easily diverges from the implementation and becomes stale
  • Comments that leave only the history of an already-resolved issue

Documentation comments (per-language conventions)

Use the format that follows the language's conventions:

  • TypeScript / JavaScript: JSDoc (/** ... */)
  • Python: docstring ("""...""")
  • Rust: /// (Item) / //! (Module)
  • Go: // FuncName ... format
  • Java / Kotlin: Javadoc (/** ... */)
  • Other: follow the conventions of the language's official documentation

Write the "role and boundary" in the leading summary line, and add the caller, callee context, and non-obvious constraints in the body.

Inline comment

Write why (why it is implemented that way). The what is shown by the code. Write constraints, background, and specification-related reasons immediately before the relevant line or block. Actively include external information that should be referenced (issue numbers, specification URLs).

Good examples and bad examples

Bad example (verbatim restatement of the what):

/**
 * ユーザーIDを受け取り、ユーザー情報を返す。
 * @param userId ユーザーID
 * @returns ユーザー情報
 */
function getUser(userId: string): User | null { ... }

Good example (including the role and the perspective from elsewhere):

/**
 * 認証レイヤーの公開インターフェース。API ハンドラーから呼ばれ、
 * セッション検証済みの呼び出しのみを前提とする(未認証は上流ミドルウェアで遮断)。
 *
 * UserRepository に委譲し、DB から取得した値を返す。
 * 存在しない場合は null を返す(例外は投げない)——
 * 呼び出し元は null チェックを必ず行うこと。
 *
 * 注: soft delete されたユーザーも null として扱う(仕様: issue #142)。
 */
function getUser(userId: string): User | null { ... }

Step 4: Perform a self-check

Review the comments you added or reinforced from the following perspectives.

Accuracy of the content

  • Is it not an obvious verbatim explanation or a restatement of the what?
  • Is it not writing content that diverges from the implementation (does it not contradict the signature)?
  • Are the investigation results from Step 2 (callers, dependencies) correctly reflected in the comments?

Security (mandatory check)

  • Are secrets such as API keys, tokens, or passwords not written in comments?
  • Is personal information (PII) not directly written in comments (for example, user IDs)?
  • Are the preconditions for authentication and authorization not described in a misleading way (such as an erroneous note like "authentication not required")?
  • Are security constraints and permission assumptions described clearly and accurately?

If a problem is found in the above check, fix the comment content before proceeding.

Japanese style

  • Is it written in plain style (da/dearu style)?
  • Are commands, identifiers, and file names left in English (not translated)?
  • Is there no excessive use of emoji?

Step 5: Present the diff and report

Present the changes in diff format and report in the following format.

## comment-code 完了報告

### 対象ファイル
- `path/to/file.ts`(追加: N 件、補強: M 件)

### 追加したコメントの観点
- 呼び出し元: [どこから呼ばれるかを明記した箇所]
- 呼び出し先との契約: [返値・エラー条件を明記した箇所]
- 非自明な制約・背景: [why を記述した箇所]

### セキュリティチェック
- 結果: ✅ 問題なし / ⚠️ 警告あり(詳細)

### 次のアクション
- コミットする場合: create-commit スキルを使用
- CLAUDE.md を更新する場合: update-docs スキルを使用

The commit is create-commit Delegate to the skill (this skill itself does not perform commits).

Verification

After adding comments, verify the following.

git diff HEAD
  • That the code logic (function body, control flow) has not been changed
  • That the added comments do not contradict the implementation
  • That all of the Step 4 self-checklist items have passed

Common failures

Problem Workaround
Writing verbatim what is obvious from the signature/type (a paraphrase of the what) Write only non-obvious information, such as "why this implementation" or "the caller's assumptions"
Writing comments based on guesswork without investigating the caller In Step 2, always check the caller with grep before writing
Mixing secrets or personal information into comments In the Step 4 security check, confirm there is no secret information or PII
Changing the code logic "while tidying it up" For places that require implementation changes, leave a TODO in a comment andimplement-issue guide to

Notes

  • Do not change the code logic — Only add or reinforce comments. If you determine there is a problem with the implementation, implement-issue guide to the skill
  • Keep comments in sync with the implementation — If existing comments diverge from the implementation, fix them (divergent comments are more harmful than accurate comments)
  • Follow the target repository's detailed conventions — .claude/rules/code-comment-style.md If it exists, prioritize it. The key points of Step 3 in this skill function as a fallback when that file is not in place
  • Assume AI agents are also readers — Write on the assumption that "you can understand by referring to other files" does not apply. Agents such as Claude use comments as a primary source of context
  • --no-verify Bypassing pre-commit hooks such as this is prohibited. If a hook fails at commit time, investigate and fix the cause before re-running