| name | code-comment |
| description | English code comment standards for Python and TypeScript. Use when (1) adding comments to code, (2) standardizing comment format, (3) TypeScript/TSX file header comments, (4) Python module docstrings |
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 | Name + description + metadata tags |
| Header content | Describe what it is, NOT how it's implemented |
| Forbidden in header | ❌ User Story IDs (e.g. US-107) — belong in Git commits |
| Forbidden in header | ❌ Implementation details (e.g. "uses shadcn/ui") — self-evident from code |
@module tag | ✅ Required — matches directory path (e.g. features/chat, core/config) |
@template tag | ✅ Required — template from .agent/templates/, or none if no template |
@reference tag | ✅ Required — external project or best practice source, or none |
| Function docs | Concise English docstring |
| Inline comments | English, placed ABOVE code, not beside it |
| Code spacing | Blank line between code blocks |
⚠️ Critical: @template and @reference Relationship
-
If @template is set → @reference MUST also be set.
Every template was extracted from an external project. Open the template file, find its @source or @reference, and carry it forward.
-
@reference path format: Use project-name/path/to/file (file-level), NOT a URL.
- ✅
@reference rag-web-ui/frontend/src/lib/api.ts
- ✅
@reference shadcn-admin/src/components/confirm-dialog.tsx
- ❌
@reference https://github.com/xyb/rag-web-ui (URL, not file path)
- ❌
@reference rag-web-ui (project-level only, not specific enough)
-
Only when @template none AND no external inspiration → @reference none.
Part A: Python
1. File-level Docstring
Every .py file MUST have a module docstring at the top, before imports.
Standard format:
"""
ModuleName - Short description of what this module does
@module app/chat/service
@template A10 backend/domain/service.py — Generic CRUD Service Layer
@reference none
"""
Field rules:
| Field | Required | Description |
|---|
| Line 1 | ✅ | ModuleName - Brief description |
@module | ✅ | Python module path matching directory (e.g. app/chat/service) |
@template | ✅ | Template ID + path, or none if no template applies |
@reference | ✅ | External reference project or best practice, or none |
2. File-level Docstring Examples
Service layer (with template):
"""
ChatHistoryService - Manages persistence of chat sessions and messages
@module app/chat/service
@template A10 backend/domain/service.py — Generic CRUD Service Layer
@reference none
"""
Configuration module (with reference):
"""
AppConfig - Manages environment variables and application settings using pydantic-settings
@module app/core/config
@template none
@reference full-stack-fastapi-template/backend/app/core/config.py
@reference fastapi-best-practices §1 Project Structure
"""
Azure integration (with template + reference):
"""
AzureOpenAIService - Provides LLM chat completion, streaming, and embedding generation
@module app/azure/openai
@template F3 backend/azure/openai_error.py — OpenAI Adapter + Streaming Chat
@reference azure-search-openai-demo/app/backend/approaches/
"""
Business-specific module (no template, no reference):
"""
ChartDataExtractor - Extracts structured chart data from document content using LLM and regex fallback
@module app/research/service
@template none
@reference none
"""
Route module:
"""
ChatRoutes - RESTful endpoints for chat session CRUD and message operations
@module app/chat/routes
@template A8 backend/domain/routes.py — FastAPI Router with Depends
@reference none
"""
Schema module:
"""
ChatSchemas - Pydantic schemas for request/response validation in chat endpoints
@module app/chat/schemas
@template A9 backend/domain/schemas.py — Pydantic Request/Response Models
@reference none
"""
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
1. File-level JSDoc
Every .tsx / .ts file MUST have a JSDoc block at the top, before imports.
Standard format:
Field rules:
| Field | Required | Description |
|---|
| Line 1 | ✅ | ComponentName - Brief description |
@module | ✅ | Module path matching directory structure (e.g. features/chat, shared/components/ui) |
@template | ✅ | Template path, or none if no template applies |
@reference | ✅ | External reference project or best practice, or none |
2. File-level JSDoc Examples
Feature component aligned with template:
Business-specific component (no template):
Shared UI component:
Custom Hook:
Page / View component:
Service / API layer:
Type definition file:
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
