每个开发者都会讨厌两件事情——阅读没有注释的代码和给代码写注释。虽然无注释的代码也许终不可得,但是审视我们的代码结构减少注释,那也是非常值得的。那么如何正确地给代码给注释呢?
本期话题
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、减少注释但依然能让他人看得懂代码的方法:
编写有意义的变量名、函数名,使代码自解释。
遵循一定的代码格式和规范,如函数/方法命名、缩进、空格等。
在关键地方添加注释,解释为什么这样做,而不是仅仅描述代码做什么。
使用有意义的空行和段落,将代码逻辑分区,便于阅读。
编写单元测试和文档,通过测试用例解释代码行为,文档描述模块功能和接口。
版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。
随着企业数据量的增长,有效的数据治理不仅关乎数据的质量和安全性,还涉及到如何合理利用有限的资源来达到成本效益最大化的目的。数据治理又跟数据生命周期管理密不可分,数据生命周期管理是确保数据在其整个生命周期内得到有效管理和使用的策略。它涉及从数据创建到数据过期的整个过程,包括数据的存储、保护、归档和销毁。通过实施DLM,企业可以确保数据在各个阶段都得到适当的处理,从而平衡数据可用性、成本控制和合...
大型AI模型面临的“专门化智能”的局限主要体现在理解力、泛化能力和适应性等方面。这些局限性使得大型模型在特定任务上虽然表现优异,但在更复杂的问题、多轮对话和原理性问题上仍存在挑战。 增强数据的多样性和质量 数据增强技术:通过旋转、平移、缩放等操作增强图像数据,或在自然语言处理中使用同义词替换、随机插入、删除等方法扩展语料库,可以有效提高模型的泛化能力。 高质量数据集的构建:构建大规模、高质量...
1. 教育互动性的增强 智能眼镜提供了一种新的交互方式,可以通过语音、手势等多种方式进行信息检索和交互,这对于提高学生的学习积极性具有重要意义。例如,学生可以通过简单的语音指令快速查询到所需的学术资料或解答,而无需打开电脑或手机。这种即时的信息获取方式可以极大地提升学习效率,增加学习的趣味性,从而激发学生的学习兴趣。 2. 实时信息的提供与更新 在传统教育模式下,教材和教师提供的信息往往存在...
人机共生:在AI的高效与人类创造力之间寻找平衡 随着人工智能技术的飞速发展,它已经以前所未有的速度融入我们的日常生活和各行各业。从自动化生产到个性化服务,AI的应用几乎无所不在,带来了效率和便利的同时,也引发了对于工作岗位、人类创造力等问题的深刻讨论。面对这一挑战,我们如何在人工智能的高效自动化与人类独有的情感智慧、创新能力之间寻求一个和谐的平衡点?如何在享受技术红利的同时,保障人类工作的价...
# 我选择使用通义(工具箱)^.^ 原因有以下三点: 1.钉钉直接就可以用,以前一直都只能用的钉钉打卡,深恶痛觉。直到收到了推送可以直接用千问了。(其他大模型还得额外下载app或每次网页登陆,麻烦) 2.可以定制在自己的大模型,我已经成功做了一个企业知识库(百炼-appflow-钉钉),选择基础模型,一次调用对话才0.1-0.2r,划算~ 3.还可以画画,写代码,分析文章,写材料等等等,十分...