每个开发者都会讨厌两件事情——阅读没有注释的代码和给代码写注释。虽然无注释的代码也许终不可得,但是审视我们的代码结构减少注释,那也是非常值得的。那么如何正确地给代码给注释呢?
本期话题
1、工作中你遇到过的糟糕注释或优秀注释有哪些?
2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
本期奖励:
截止2024年1月10日24时,参与本期话题讨论,将会选出5名幸运用户获得笔记本电脑包*1
幸运用户获奖规则:中奖楼层百分比为17%,32%、53%,76%、94%的有效留言用户可获得互动幸运奖。如:活动结束后,回复为100层,则获奖楼层为 100✖17%=17,依此类推,即第32、53、76、94位回答用户获奖。如遇非整数,则向后取整。如:回复楼层为84层,则84✖17%=14.28,则第15楼获奖。
未获得实物礼品的参与者将有机会获得 10-200 积分的奖励。
注:楼层需为有效回答(符合互动主题),灌水/复制回答将自动顺延至下一层。如有复制抄袭、不当言论等回答将不予发奖。阿里云开发者社区有权对回答进行删除。获奖名单将于活动结束后5个工作日内公布,奖品将于7个工作日内进行发放,节假日顺延。
1、工作中你遇到过的糟糕注释或优秀注释有哪些?
遇到过完全没有注释、注释和代码毫无关系、离职的人给后人留下的大坑
2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
建立规范化的代码体系、构建一本账管理对相关代码建立索引机制
1、工作中你遇到过的糟糕注释或优秀注释有哪些?
完全不写注释。方法名 参数名随意
注释与代码不一致,留下过时的注释导致误导。
注释使用拼写错误、语法错误,或者没有遵循团队约定。
2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗
良好的命名和自解释的代码,使用正确的英文单词命名
注释的目的是为了解释代码的功能、实现思路、注意事项等,提升代码的可读性和可维护性。
1.简单业务功能,如增删改查,简单注明即可,如:create、delete、edit、select。
2.复杂业务功能,使用索引,链接到企业知识库或者网络文库、博客等。
/**
* <a href="https://aliyun.com">业务功能说明</a>
*/
public List<DiscordAccount> list(){
return this.loadBalancer.getAllInstances().stream().map(DiscordInstance::account).toList();
}
# 增加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");
}
# 糟糕的注释
def calc(a, b):
result = a + b # 将a和b相加得到结果
return result
# 优秀的例子
def add_numbers(num1, num2):
return num1 + num2
# 糟糕的注释
# 处理用户输入,验证并保存到数据库
# ...
# 验证邮箱格式是否正确
# ...
# 保存用户信息到数据库
# ...
# 优秀的注释
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):
# 保存用户信息到数据库的代码
// 糟糕的例子
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的代码
}
1、工作中你遇到过的糟糕注释或优秀注释有哪些?
糟糕的例子://注释“某年某月谁改的“
OS 这名字都不知道是否还在这个碳基世界,目前的形态是碳基还是炭集,写的这个鬼注释仿若大圣五指山前留得那个记号,有个浮云用。
优秀://存在原因+参数应用范围+举例
2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗
难办难办 经常看到一个代码写得一塌糊涂,注释乱七八糟,观者恨不得问候代码创造者,发现出自己手。
不然就像word插入注释一般,又影增加冗余响速度。
2有一些方法可以减少注释,但依然能让他人看懂代码:
使用有意义的变量和函数命名:选择具有描述性的变量和函数名称,可以减少对注释的需求。通过命名清晰地表达代码的意图和功能。
模块化和函数化:将代码分解为小的模块和函数,每个模块和函数只关注单一的功能,减少代码的复杂性和理解难度。
编写自解释的代码:通过良好的代码结构、逻辑和设计模式,使代码本身尽可能地清晰地表达其意图和功能。
添加文档注释:在函数和类的开头,使用适当的文档注释(如Javadoc或Python的docstring)来描述函数的输入、输出和功能。
提供示例代码:在代码中添加一些示例用法,可以帮助其他开发者更好地理解代码的使用方式和预期行为。
2减少注释但保证可读的方法,我会:
注重代码结构和命名的可读性。
使用自 explanatory 的函数/变量名字。
注释重要的逻辑变化或 boundary case。
注释公共库或复杂算法。
加入必要的测试用例。
保持简洁高效的代码风格。
糟糕的注释可能包括以下几种情况:
没有注释:完全没有注释,或者只有少量的注释,导致代码缺乏解释和文档,使得其他开发者难以理解代码的意图和功能。
冗长而无用的注释:注释内容过多,但没有提供实质性的信息,只是重复了代码本身已经表达的内容。这样的注释会增加代码的冗余,降低可读性。
错误的注释:注释与代码不一致,或者过时的注释导致误导。如果注释不反映实际的代码逻辑或者没有及时更新,那么将给其他开发者带来困惑和错误的理解。
不规范的注释:注释使用拼写错误、语法错误,或者没有遵循团队约定和最佳实践。不规范的注释会给阅读者带来困惑,降低代码的可读性和专业性。
过度注释:在每一行或每一个语句都添加详细注释,而这些注释对于理解代码并无实际帮助。过度注释会干扰代码的阅读,使得代码显得混乱。
单行注释过长:单行注释过长,超过一定的长度限制,难以阅读。注释应该简洁明了,提供必要的信息,避免过度冗长。
1、工作中你遇到过的糟糕注释或优秀注释有哪些?
经常遇到,非常依赖程序员的水平,糟糕注释居多,大多数的注释都是很简单,只有自己知道的那种
2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
最好是团队有个明确的规范,对代码命名,格式等做出要求,这样就可以减少一些注释也能让团队中的人明白意思
2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
我觉得尽量还是要多注释,这个比较看程序员的阅读代码的水平,正常的做法就是对一些命名能够有含义,对代码结构进行拆解,不要全部写在一起
1 有遇到过,经常能碰到一些注释是反人类的,注释内容非常长,看的头晕的那种,这种是见过最糟糕的注释
1、工作中你遇到过的糟糕注释或优秀注释有哪些?
糟糕注释一般有以下几种情况:
1没有注释:缺乏注释或者完全没有注释,使得代码难以理解和维护。
2冗长而无用的注释:注释内容过多,但没有提供实质性的信息,只是重复了代码本身已经表达的内容。
3错误的注释:注释与代码不一致,或者过时的注释导致误导。
4不规范的注释:注释使用拼写错误、语法错误,或者没有遵循团队约定和最佳实践。
优秀注释:
1解释代码意图:注释清晰地解释代码的目的、意图和设计思路,增强代码的可读性和可理解性。
2提供上下文信息:注释提供与代码相关的上下文信息,例如输入输出格式、预期行为等,有助于理解代码的作用和用途。
3说明算法或复杂逻辑:对于复杂的算法或逻辑,注释可以提供更详细的说明和解释,帮助他人理解代码的实现细节。
4提醒和警示:注释可以用来提醒和警示其他开发者可能出现的问题、注意事项或潜在的风险。
2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
使用有意义的变量和函数命名:选择具有描述性的变量和函数名称,可以减少对注释的需求。通过命名清晰地表达代码的意图和功能。在代码中添加一些示例用法,可以帮助其他开发者更好地理解代码的使用方式和预期行为。
1 优秀注释的话就是那种一眼就知道这个函数的作用,入参出参明确;糟糕的就是,要么注释很少,要么注释不明确,要么就是更新不及时的注释
1、工作中你遇到过的糟糕注释或优秀注释有哪些?
只写一行简单注解,但内容同代码意思完全不符。
2、你有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
注重代码结构和命名的可读性
1、工作中遇到的糟糕注释:
过于简单,只写“此处进行数据验证”但没有具体说明如何验证。
过时或与代码实际功能不符,导致读者误解。
注释过于冗长,描述过于详细,读起来很费劲。
工作中遇到的优秀注释:
清晰、简洁,能够准确描述代码功能或意图。
适当使用中文注释,便于团队成员理解。
描述算法或复杂逻辑时,会使用“首先...然后...最后...”等结构化语句。
2、减少注释但依然能让他人看得懂代码的方法:
编写有意义的变量名、函数名,使代码自解释。
遵循一定的代码格式和规范,如函数/方法命名、缩进、空格等。
在关键地方添加注释,解释为什么这样做,而不是仅仅描述代码做什么。
使用有意义的空行和段落,将代码逻辑分区,便于阅读。
编写单元测试和文档,通过测试用例解释代码行为,文档描述模块功能和接口。
版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。
常规知识: 在回答常规问题时,通义大模型回答质量时好时劣,如下: 这个问题的回答,右边的模型更优。 而这个回答,左边的模型又表现得更好。 逻辑判断 两个模型都做出了正确的回答,但从通俗易懂上来说,模型A显然更好。 而在这道题中,两者的回答都一致,但都对了一部分。 下面就针对市面上较为大众的模型开展专项测试,看看到底哪家相对较强,参与测试的模型有:百度的文心一言ERNIE 4.0、阿里的通义千...
一条SQL语句的执行究竟经历了哪些过程 以下是这个过程中可能涉及的主要步骤: 1.词法分析:数据库管理系统首先将SQL语句分解成一系列的标记,如关键字、标识符、运算符和常量等。为后续的语法分析做好准备。 2.语法分析:接下来,数据库管理系统会检查这些标记是否符合SQL的语法规则,并构建一个抽象语法树。 3.语义分析:数据库管理系统会对AST进行检查,确保所有的表、列和数据类型都是有效的,并且...
小程序的优势: 不需要用户下载app,微信、支付宝、百度、抖音等各大平台中直接打开对应的小程序;各大平台有大流量,用户量极大;比开发app成本低,不用像app上架那样麻烦。 如果构建小程序,会用在个人博客、预约服务、便民信息查询等。 想要简单的构建多平台的小程序呢,可以使用跨平台框架:选择一个成熟的跨平台开发框架是关键。目前市场上比较流行的有uni-app、Taro、Kbone等。 我希望了...
我认为是机会,因为开发者可以利用AI工具和平台来增强他们的开发能力,例如通过使用AI来分析用户行为来改进产品之类。
想要正确发展, 用于正途, 就需要明确版权和隐私保护,对于已故人物的影像、声音、语言等数据,需明确其版权归属及使用权限,避免未经授权的滥用。同时,制定严格的隐私保护法,确保个人数据在数字化过程中不被滥用。在法律层面上确立相关伦理规范,禁止利用数字复活技术进行欺诈、虚假宣传或其他不道德行为。例如,禁止在未经本人及其亲属同意的情况下,商业化利用已故人物的数字形象。制定统一的技术标准,确保数字复活...