| name | code-comment |
| description | 中英文双语代码注释规范。Use when (1) 为代码添加注释, (2) 需要中英双语文档, (3) 规范化代码注释格式, (4) 学习类项目代码注释 |
Code Comment (Bilingual)
Objectives
- Add bilingual (Chinese & English) comments to code
- Follow consistent comment formatting rules
- Explain complex logic with reasons
- Maintain clear code documentation
Comment Rules Overview
| Location | Language | Format |
|---|
| File-level docstring | English only | Standard docstring |
| Function docstring | Chinese + English | Two-line format: Chinese first line, English second line |
| Inline comments | Chinese + English | Chinese line, then English line, above code |
| Code spacing | - | Blank line between code blocks |
1. File-level Docstring (English Only)
"""
Lab 2: Q-Learning Agent for Cliff Walking
Student ID: 041107730
Implements Q-Learning using Bellman equation: Q(s,a) = r + γ * max Q(s',a')
Modified from Hybrid Activity 1 to solve the Cliff Walking problem.
"""
2. Function Docstring (Two-Line Bilingual Format)
Two lines with Chinese first line, English second line:
def train(env, episodes: int = 50, gamma: float = 0.9) -> list:
"""训练Q-Learning智能体
Train Q-Learning agent"""
def reset() -> tuple:
"""重置环境到初始状态
Reset environment to initial state"""
Rules:
- Use triple quotes
"""
- Chinese description on first line
- English description on second line
- Keep it concise, no blank line between Chinese and English
- No parameter or return value details in docstring
3. Inline Comments (Line-by-Line Bilingual)
Chinese comment immediately followed by English comment, placed ABOVE code:
qtable = [[random.random() for _ in range(env.actions())] for _ in range(env.states())]
steps += 1
Rules:
- Comment goes ABOVE the code, NOT beside it
- Chinese line first, English line immediately after (no blank line between)
- Blank line AFTER comments and before next code block
- For complex logic, add explanation:
qtable[state][action] = reward + gamma * max(qtable[next_state])
epsilon -= decay * epsilon
4. Code Spacing
IMPORTANT: Always add blank lines between code blocks:
def main():
print("=" * 50)
env = GridEnv(size=12)
EPISODES = 50
GAMMA = 0.9
Rules:
- Blank line after each code block
- No blank line between Chinese and English comments
- Comments always above code, never beside it
5. Complex Logic Comments
For complex logic with multiple lines, keep Chinese and English paired line-by-line:
qtable[state][action] = reward + gamma * max(qtable[next_state])
if self.y == 3 and 1 <= self.x <= 10:
reward = -100
6. Import Comments
Add bilingual comments above imports:
import abc
import os
import time
import random
7. Entry Point Comment
if __name__ == "__main__":
main()
Comment Checklist
Before finishing:
Quick Reference
"""
Lab 2: Q-Learning Agent
Implements Q-Learning algorithm
"""
def train(env):
"""训练Q-Learning智能体
Train Q-Learning agent"""
qtable = [[random.random() for _ in range(env.actions())] for _ in range(env.states())]
steps += 1
Key Rules Summary
- Function docstrings: Two lines - Chinese first line, English second line (NO blank line between)
- Inline comments: Chinese line, English line, then code (NO blank line between Chinese/English)
- Comment placement: Always ABOVE code, never beside it
- Code spacing: Blank line after each code block
- No blank line: Between Chinese and English lines (both in docstrings and comments)
Complete Example
"""
Lab 2: Q-Learning Agent for Cliff Walking
Student ID: 041107730
Implements Q-Learning using Bellman equation
"""
import abc
import os
import time
import random
class Env(abc.ABC):
"""环境抽象基类
Environment abstract base class"""
@abc.abstractmethod
def actions(self) -> int:
"""返回动作空间的大小
Return the size of action space"""
raise NotImplementedError()
def train(env, episodes: int = 50, gamma: float = 0.9) -> list:
"""训练Q-Learning智能体
Train Q-Learning agent"""
qtable = [[random.random() for _ in range(env.actions())] for _ in range(env.states())]
for episode in range(episodes):
state = env.reset()
qtable[state][action] = reward + gamma * (qtable[next_state])
qtable
__name__ == :
main()
