如何正确地给代码写注释?
糟糕的注释:
# 增加1到变量
counter += 1
// 如果x小于10,执行下面的代码
if (x 10) {
// 做一些事情
doSomething();
}
优秀的注释:
# 该循环用于计算数组元素的总和
total_sum = 0
for num in numbers:
total_sum += num
// 验证用户是否已登录
if (user.isAuthenticated()) {
// 在数据库中保存用户信息
saveUserData(user);
} else {
// 如果未登录,记录错误日志
logError('User not authenticated');
}
减少注释的方法:
1. 良好的命名和自解释的代码:
# 糟糕的注释
def calc(a, b):
result = a + b # 将a和b相加得到结果
return result
# 优秀的例子
def add_numbers(num1, num2):
return num1 + num2
2. 模块化和函数化:
# 糟糕的注释
# 处理用户输入,验证并保存到数据库
# ...
# 验证邮箱格式是否正确
# ...
# 保存用户信息到数据库
# ...
# 优秀的注释
def process_user_input(input_data):
validate_and_save_to_database(input_data)
def validate_and_save_to_database(data):
validate_email_format(data['email'])
save_user_data_to_database(data)
def validate_email_format(email):
# 验证邮箱格式的代码
def save_user_data_to_database(user_data):
# 保存用户信息到数据库的代码
3. 自解释的代码结构:
// 糟糕的例子
function complexFunction(x, y, z) {
// 一大堆复杂的代码
// ...
}
// 优秀的代码
function separateTasks(x, y, z) {
performTask1(x);
performTask2(y);
performTask3(z);
}
function performTask1(parameter) {
// 任务1的代码
}
function performTask2(parameter) {
// 任务2的代码
}
function performTask3(parameter) {
// 任务3的代码
}
赞17
踩0