| name | code-comment |
| description | English code comment standards for Python and TypeScript. Use when (1) adding comments to code, (2) standardizing comment format, (3) inline comment placement, (4) section dividers |
Code Comment Standards
Objectives
- Add clear, English-only comments to code
- Follow consistent comment formatting rules per language (Python / TypeScript)
- Explain complex logic with reasons
- Maintain clear code documentation
Shared Principles (All Languages)
| Principle | Rule |
|---|
| Language | English only |
| File header | See file-templates.md — single source of truth |
| Function docs | Concise English docstring |
| Inline comments | English, placed ABOVE code, not beside it |
| Code spacing | Blank line between code blocks |
Part A: Python
File header format → see file-templates.md § 一
3. Class Docstring (One Line)
class ChatHistoryService:
"""Chat history persistence service."""
class AzureOpenAIError(Exception):
"""Azure OpenAI service error."""
4. Function Docstring
Concise English docstring. For complex functions, include Args/Returns.
Simple function (one-liner):
def _validate_config(self) -> None:
"""Validate required configuration."""
@staticmethod
def _doc_to_session(doc: UniversalDocument) -> dict:
"""Convert UniversalDocument to session response dict."""
Complex function (with Args/Returns):
async def create_session(self, owner_id: str, title: str | None = None) -> dict:
"""Create a new chat session.
Args:
owner_id: User ID.
title: Session title.
Returns:
Session dict.
"""
Rules:
- Keep it concise
- Args/Returns for complex functions only
- Skip for trivial getters/setters
5. Inline Comments
English comments placed ABOVE the code:
data = dict(doc.data)
if len(user_messages) == 1 and role == ChatRole.USER:
data["title"] = content[:50]
Rules:
- Comment ABOVE code, never beside it
- Blank line between code blocks
- For complex logic, add reason:
response = await self._openai_service.chat_completion(
messages=[{"role": "user", "content": prompt}],
temperature=0.1,
)
6. Section Dividers
Use three-line box dividers (60 = characters) to group related methods within a class:
class ChatHistoryService:
async def create_session(self, ...) -> dict:
...
async def list_sessions(self, ...) -> list[dict]:
...
async def append_message(self, ...) -> dict | None:
...
async def _get_session_doc(self, ...) -> UniversalDocument | None:
...
7. Import Comments
Do NOT comment obvious imports. Only add comments for non-obvious choices:
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from app.azure.openai import AzureOpenAIService
Part B: TypeScript / TSX
File header format → see file-templates.md § 三
3. Function / Hook Comments (JSDoc)
Use JSDoc above exported functions:
export function useChatStream(baseUrl: string) { ... }
function formatConfidence(value: number): string { ... }
Rules:
- Keep it concise — no
@param / @returns unless the types are non-obvious
- Use for exported functions and complex internal functions
4. Inline Comments
English comments placed ABOVE the code:
scrollRef.current?.scrollIntoView({ behavior: "smooth" });
const msgId = nanoid();
Rules:
- Comment ABOVE code, never beside it
- Blank line between code blocks
- Skip trivial comments — do NOT comment obvious JSX structure
5. Import Comments
Do NOT comment obvious imports:
import { nanoid } from "nanoid";
Comment Checklist
Before finishing, verify per language:
Python
TypeScript / TSX