码农的自我修养——对代码注释的理解(转)

老码农的自我修养:为什么会有BUG?过来人告诉你! 一、为什么会产生BUG 首先我们需要尝试理解一下什么Bug? 关于bug的解释 bug 是指任何计算机程序或硬件系统中的错误,故障或缺陷。错误会产生意外结果或导致系统意外运行 简单来说:bug就是程序出了问题,产生了意外的结果,没有按照预期的结果去运行。 产生Bug的原因有很多种: 开发者水平太低 不同的编译及运行环境 与需求方沟通不到位 马虎大意、考虑不周 放飞自我,Coding全靠自嗨 选择了错误的或者运行不稳定的第三方库 以上原因总结,主观和客观因素都会影响到Bug的产生,.. 阅读详情

如何写好代码注释是一个老话题,可以说一千个程序员就有一千种不同的理解。
下面是从我自己工作中所看到的,所听到的,结合自己编码的体会谈一下自己的想法。

对代码注释的态度大致有三种误区:

1、注释很重要,每一行代码都要写注释。
2、注释可有可无,为了应付公司的编程规范,QA 的审查,开始拷贝一些函数头注释,拷过去什么都不改,连原作者名都不改,只为满足代码注释率的要求
3、无需注释,代码即注释。

第一种

新员工热情很高,也很有责任心,导师或者项目经理说要把注释写清楚啊。于是乎我们就屁颠屁颠的每个变量,每个分支,每行代码都加上注释。有时候写了一句注释生怕别人不理解,在加一句注释来注释前一句注释。

写了很多日后自己看起来都会发笑的注释:

<!-- 告诉浏览器本段代码是使用HTML5编写的 -->
<!DOCTYPE html>
<!-- html标签开始 -->
<html>
<!-- head标签开始 -->
<head>
    <!-- 网页的标题 -->
    <title>定义文档内嵌代码</title>
    <!-- 网页的编码 -->
    <meta charset="utf-8">
    <!-- 设定网页尺寸自适应 -->
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <!-- 网页的关键词 -->
    <meta name="keywords" content="小甲鱼,Web开发,HTML5,CSS3,Web编程教学">
    <!-- 网页的内容描述 -->
    <meta name="description" content="《零基础入门学习Web开发》案例演示">
    <!-- 网页的开发者 -->
    <meta name="author" content="小甲鱼">
<!-- head标签结束 -->
</head>
<!-- body标签开始 -->
<body>
    <!-- 显示一段文本 -->
    <p>上面的内容哪来的?</p>
    <!-- 使用 JavaScript 技术,在网页中插入 I love FishC.com! -->
    <script type="text/javascript">
        document.write("I love FishC.com!");
    </script>
<!-- body标签结束 -->
</body>
<!-- html标签结束 -->
</html>

工作久了再来回过头来看这些代码注释,犹如脱裤子放屁般淡定地陈述一句非常正确的废话。但是,谁没有个当年呢,谁没有装个 B 的时候。回味一下也是一段非常有意思的记忆。

第二种

业务基本上混熟了,也能在项目中承担一些核心的任务。觉得编码就是体力活(有时确实也是),只要功能实现了,代码那怕写得像一坨 si 也无所谓,拷贝粘贴就 OK 了。

这个阶段往往开始考虑是走技术路线还是走管理路线了,走技术路线是走业务分析路线还是走架构设计路线。如果是有抱着前面描述想法的建议走技术的业务分析路线或者管理路线,走软件设计方向估计你没兴趣。我就认识几个人,开发时写的代码在后续版本维护和增量开发的过程中无法扩展,改着改着几乎删了重写了;但这哥们业务研究的深入,转行做 SE,现在转 Marketing,也混得风生水起。所以说不想写代码,写烂代码并一定就是你的错,可能你的兴趣就不在这里,找准自己的方向。

第三种

读过两本大师著作,不知道从哪听到了“代码即注释,代码即设计,代码即文档,代码即 XXX”。

总之,代码注释越少越是觉得自己牛 X 。有时候维护的过程中或者代码检视的过程中看到这样的代码,大函数,圈复杂度老高,夹杂中式英语,全篇无注释。看到有歧义的地方想问一下都不知道问谁。真想吼一声:请注释你那该死的代码,你看它就是一坨 si!

我们倡导代码自注释,通过恰当的命名,合理的结构划分让代码说话。但是不得不承认,代码作为人与计算机交互的语言,它的表达力,可理解性和人与人之间交流,经过千锤百炼的自然语言相比还是比较弱的。恰当有效的注释不仅是值得鼓励的而且是必须的。

通过实际经验对比发现:真正的编程高手不光代码写的漂亮,注释也写得相当漂亮,很多时候寥寥几笔注释起到画龙点睛的作用。而信仰并实践着代码即注释的人大部分都是半桶水。可以说看一个程序的代码写得怎么样,就看他的注释写得怎么样。

下面说说我对好代码注释的理解:

1. 注释首先要告诉维护的人这段代码是谁写的。

很多代码没有函数头注释,不知道是不屑写还是怕写。这不是一个好习惯,由于代码从开发到维护经常会换几拨人,新手未必能理解你当时的意图,这时能找人问一下是多么重要。将心比心,如果让你去维护一大块代码,看不懂又不知道问谁,估计也忍不住要破口大骂。

虽然现代的软件开发都是有版本控制,比较版本树能找到谁写的代码。但是,日积月累每个文件的版本节点数百个,从里面去找出某个函数,某处修改是数字写的也是很难得。

从我个人的理解,写代码不写函数头注释要么是太自信,要么是太不自信。

2. 注释不是描述代码做了什么而是描述为什么这么做。

如上面举例的,注释将代码做的事情用语言再描述一遍,其实是画蛇添足。维护的人或者看代码的人,最想知道的是为什么这么做,是为了解决什么特殊问题吗?有没有什么复杂的业务背景。至于怎么做,看代码就知道了。

当然,对于业务逻辑实在太复杂的部分。看代码不是能一下就看出个所以然来,通过一段文字说明,把关键点点出来,还是很有好处的。

3. 注释描述的内容应该和代码是一致的。

这个就不说了,做过软件开发的人都知道。修改代码时未同步修改注释,注释成了误导。需要说一下,错误的注释比没有注释更糟糕。

4. 函数头注释应该描述函数调用的前置条件和后置条件。

函数作为供其它函数调用的一个接口,需要有它的使用说明书。在什么场景下使用,使用后会产生什么样的后果,使用须知等。比如该函数的返回的指针需要调用方主动释放内存,如果调用方没有释放就导致内存泄露。

5. 取一个有意义的函数名,让它注释自己。

函数是一个功能单元,做一件事情。函数名最好能定义为动宾结构,最好能具体一点。比如校验用户名,校验密码可以是 CheckUserName、CheckPassword,而一个比较空泛的名称就不好理解,像 DoChecking 之类的。

开发过程中经常看到这样的情况:某个功能要处理 A、B、C 三件事,拆分成三个函数,函数名就是 DoA、DoB、DoC。只能说太随意了,还可以再斟酌一下。还可以做得更好。

6. 取一个好的变量名,让人不易误用。

见过字符串变量就直接定义叫 str,某个结构体量定义叫 st。或者有时候函数中的临时变量不知道定义什么名称,干脆叫 temp1、temp2、temp3……抓狂 T_T

7. 好的代码注释应该告诉后来人维护的思路。

维护过程中发现的好注释。代码注释不仅展示了作者清晰的思路,还将作者对后续可能的变化的思考也融入进来了。作者在写代码时已经考虑了后续版本的需求哪里可能会变化,变化后只要怎么修改一下哪里的代码就可以支持。这样的代码注释看起来很舒心,作者是有思想的,也是负责任的。

实战对比:Lmcache+vllm将KVcache卸载到CPU和SSD的性能差异(附完整配置) 本文通过实战对比Lmcache与vLLM在KV Cache卸载到CPU和SSD的性能差异,详细解析了配置优化、基准测试及高级调优策略。实验显示,CPU卸载在低并发下表现优异,而SSD方案在高并发场景中更具性价比优势,为LLM推理任务提供了高效的存储解决方案。 阅读详情

相关推荐

如何导入su_利用GIS快速生成SU场地模型

01|前言:进入2021年了,希望大家也是一个新的开始。告诫自己多写文章多更新,多读点书多旅行。然而元旦由于出去玩了4天,积累了一些事情要处理,一直没有时间好好写点东西。今天给大家带来的分享主题叫“利用GIS快速生成SU场地模型”。相关的视频方法其实B站上也有,但我相信视频很多人都不会看,我自己也是。直接给大家上操作流程。主要的操作步骤是【获取场地的矢量shp文件】—【导入ArcScen...

weixin_33806859的博客 9817

编程基本功:代码即注释,文字类注释要谨慎

  关于注释,吾有几个言论: 注释无用。 注释有害。因为对错不知。写的人意思很难表达清楚,表达清楚了阅读者很难正确理解。 前一文,吾提出一个惊天神论:注释是程序员赠送给公司的,不写也没错。这比注释无用论、有害论更进了一步。   有人就奇怪了,大哥你说注释无用、注释有害,那么什么有用?当然是代码啊。代码是程序员的工作,做好工作才是关键。实际上现在要求写好代码,代码就是注释。包括: 命名清楚、准确。文件名、类名、函数名、字段名、参数名、变量名,没有歧义。比如说,在视图中不要用left表示剩下的意思,因为

柳鲲鹏 1270

AI陪伴成瘾:青少年情感依赖的形成机制与家庭干预指南

大语言模型驱动的对话式交互,正从简单的信息应答演变为具备高度共情能力的AI陪伴工具。其核心原理是模型通过学习海量人类情感表达模式,实现即时共情、记忆唤起和个性化回应,从而形成情感粘性。这种技术在提供情绪支持上有独特价值,但也可能带来情感依赖风险——尤其是对现实社交缺失的青少年群体,他们容易在算法设计的“即时反馈”与“开放结局”中逐步退缩,甚至产生社会功能退化。因此,理解AI陪伴的成瘾机制,识别预警信号,并采用先连接后干预的家庭五步法,是防止虚拟关系替代现实社交的关键。

weixin_26712075的博客 125

添加注释作者信息

添加代码作者、日期信息 近期公司项目代码核查,要求添加署名注释,以便代码追责,由于编码习惯、合作开发等各种原因,老项目代码作者信息混乱,自己写了个工具类,递归目录查询java相关的文件,添加作者和日期信息,上代码: package com.util; import java.io.*; public class FileHeaderUtil { public static void ad...

linhao_obj的博客 6996

COCO2017数据集类别分布深度解析

本文深入解析了COCO2017数据集的类别分布情况,包括80个常见物体的分类统计和样本数量分析。通过对比训练集与验证集的分布一致性,探讨了数据均衡性问题,并针对高频和低频类别提出了实用的数据预处理和模型训练建议,帮助优化计算机视觉任务的性能。

weixin_42533751的博客 370

数据中心光模块升级实录:从200G QSFP56到400G QSFP-DD的踩坑指南

本文记录了数据中心从200G QSFP56升级至400G QSFP-DD光模块的完整实战经验。文章深入剖析了升级过程中面临的兼容性、链路预算、布线、散热与功耗管理等核心挑战,并提供了具体的解决方案与排坑指南,为高速网络升级提供了宝贵的实践参考。

butter的博客 483

代码注释的三种方式

Java注释 对所写的程序进行解释说明 Java的三种注释方式 单行注释 //后面的内容为注释 多行注释 /* 其中内容为注释 */ 在java进行编译时单行注释与多行注释不被编译 文档注释(java特有) 格式:/** @author 指定java程序的作者 @version 指定源文件的版本 */ 注释内容可以被JDK提供的工具 javadoc 所解析,生成一套以网页文件形式体现的该程序的说明文档(类似API文档)。 操作方式: javadoc -d 新文件名 -aouhor -version 被编

qq_47248941的博客 2281

AI气象预报:数值模式融合与短临预警的工程实践

气象预报正经历从物理推演到数据驱动的认知范式转变。AI气象预报并非替代传统数值模式,而是通过数值模式融合弥补其在参数化误差、初值敏感性和计算效率上的固有瓶颈。其技术价值在于提升短临预警时效性与空间精度,支撑航空调度、电力调控、防洪应急等关键场景。实践中需兼顾物理一致性、可解释性与业务系统兼容性,避免纯黑箱建模带来的外推失效与不确定性缺失风险。本文聚焦AI作为超分辨率引擎、误差矫正器和短临加速器的三类落地路径,解析HEALPix投影、多尺度图建模、轻量级U-Net等核心适配方法。

weixin_28221501的博客 301

码农的自我修养-对代码注释的理解

如何写好代码注释是一个老话题,可以说一千个程序员就有一千种不同的理解。下面是从我自己工作中所看到的,所听到的,结合自己编码的体会谈一下自己的想法。对代码注释的态度大致有三种误区: 注释很重要,每一行代码都要写注释。 注释可有可无,为了应付公司的编程规范,QA的审查,开始拷贝一些函数头注释,拷过去什么都不改,连原作者名都不改,只为满足代码注释率的要求。 无需注释,代码即注释。 第一个种:新员工热情很高

Neo.Yang的专栏 5371

有限元ABAQUS软件安装后管理员身份运行报错:Cannot connect to license server system...如何解决?

🏆本文收录于 《全栈Bug调优(实战版)》 专栏,该专栏专注于分享我在真实项目开发中遇到的各类疑难Bug及其深层成因,并系统提供高效、可复现的解决思路和实操方案。无论你是刚入行的新手开发者,还是拥有多年项目经验的资深工程师,本专栏都将为你提供一条系统化、高质量的问题排查与优化路径,助力你加速成长,攻克技术壁垒,迈向技术价值最大化与职业发展的更高峰🚀!

**My Coding Family** 2079

轮式并联五连杆下肢机器人运动控制:从建模到强化学习仿真训练

本文提出了一种基于强化学习的轮式并联五连杆下肢机器人运动控制方法。首先建立了机器人的运动学和动力学模型,推导了正逆解公式,并构建了URDF模型。随后在PyBullet仿真环境中搭建了包含复杂地形的训练场景,设计了基于PPO算法的端到端控制策略,包含状态空间、动作空间和奖励函数的详细设计。通过多组仿真实验验证了该方法在台阶攀爬等任务中的有效性,为轮腿机器人运动控制提供了完整的可复现技术方案。

huanghm88的专栏 351

代码即是注释

有些开发人员喜欢在代码中写大量的注释,认为这样可以增加代码的可读性,而很多大牛却也很少写,之前也是不解。 大量的注释的确可以帮助读代码的人,更快得理解,但往往增加了我们的关注点,代码看起来也不漂亮,Jobs告诉了我,什么才是最美? 是简约之美... 又想增加代码的可读性,又想减少甚至不用注释,这是个矛盾嘛,像是一道永远无解的数字游戏,最近有些感悟,找到了答案: 思...

bajiu1997的博客 389

第14.5章 高翔博士最新开源框架Lightning-LM源码解读(五):揭秘位姿图优化核心模块,从数学原理到代码实现

本文介绍了Lightning-LM框架中的位姿图优化(PGO)模块实现。该模块通过融合多源定位信息(激光定位、激光里程计、DR等),构建并优化位姿图来获得更精确的位姿估计。 主要内容包括: 模块概况与数据流程:初始化配置→添加PGO帧→分配位姿→优化求解→更新位姿→滑动窗口 16个核心函数详解:从构造函数到边缘化处理,涵盖完整的PGO工作流程 关键技术点:噪声参数设置、优化问题构建、约束添加、异常值处理等 关键数据结构:帧队列管理、顶点和边构建、优化统计信息收集 该PGO模块采用增量式优化方式,支持多种约束

行知SLAM 1217

【编码心得】当名码农的自我修养

1、Google 》必应 》百度2、关键词空格分割。如果搜索出来的不满意,重新更换/删减关键词或者调整关键词的顺序。3、利用好图片搜索,好的图片往往都会带着优质的作者或者博文推荐。程序员的自我修养是一个全面的过程,需要不断提升技术能力、职业素养、心理调适能力和团队合作能力。通过持续学习、积极沟通、保持积极心态和勇于承担责任,祝愿大家都能成为一名合格的码农,哈哈~~我是杰叔叔,一名沪漂的码农,下期再会!

杰叔叔不是个好叔叔的博客 908

迈瑞BS系列全自动生化分析仪LIS协议接口手册(内含HL7和ASTM)

迈瑞BS系列全自动生化分析仪LIS协议接口手册,内含HL7和ASTM)

VC中sqlite的使用

在VC中对sqlite的使用,实现数据库大批数据的快速插入,读取数据库中的数据在ListCtrl中显示

码农的自我修养 - 如何阅读别人的代码

关键词:Dokuwiki, Doxygen, cscope, git , twitch.tv, freecodecamp.org 如何提高你的代码技艺,显然这个和写作一样,那就是不停的写,不停的读,然后不断重复。 Step 1,2,3: 1. Write More Code 2. Read More Code 3. Repeat Daily 对于学习和提高新技能(如编程)的一个最重要的方面是:接触到高数量、高质量的专业例子。所以不断的阅读理解高质量项目的代码,对提高自己代码水平很有帮

guoqx的专栏 1510

LinePhone3.2.7(android端最新版本) sip客户端

SIP客户端For android:LinePhone3.2.7(最新版本),官网地址:http://www.linphone.org/

三十年软件开发之路:老码农的自我修养!

【优快云编者按】“千帆过尽仍少年”,对于程序员来说,保留技术初心、不断提升实力是夯实自己的不二法则。而本文的作者,作为一名有着三十多年开发经验的“老”程序员,就在本文中详细总结了自己这些年踩过的坑和实践得出的真理,谈到了包括软件开发、团队工作、个人成长等方方面面。相信阅读本文后,会帮助你成为更优秀的程序员。 声明:本文已获作者Julio Biason翻译授权。 作者 |Juli...

优快云资讯 7652

假人有限元模型

假人模型,车辆碰撞假人有限元模型,适合做乘员安全的研究者利用

一个“程序员的自我修养”是什么?

在《喜剧之王》中,周星驰扮演的尹天仇,一直梦想成为一名演员,而他不管是在扮演跑龙套,或者在街坊中开设演员训练班,亦或成为主角时,他对待演员的态度,始终是认真,热爱而又投入的。而那一本他随身携带的书--《演员的自我修养》,尽管不知道里面具体写的是什么,但我猜,他对待演员的态度和行为,就是书中内容显示的。   于是,不禁问了问自己,作为一名程序员,一个“程序员的自我修养”是什么?   尽管我们不一定要像尹天仇那么的认真对待自己的事业,但,一些基本的修养,作为一名新时代的码农,总应该是要具备的吧。不过真要说修

weixin_45820912的博客 1076

论程序员的自我修养

《从码农到匠人:程序员接单的自我修养》揭示了独立开发者需要完成的三大转变:从雇员思维到经营者思维,从任务导向到价值导向,从被动执行到主动管理风险。文章强调技术只是基础,真正的竞争力在于将专业、商业和人性洞察融为一体,通过高质量交付、有效沟通和超越期望的服务建立个人品牌。同时指出自由职业者需要建立自律系统、知识管理体系和社群支持网络,在孤独的修行中实现技术价值与商业价值的统一。这是一场关于技术深度、商业认知和人性洞察的综合修炼。

2303_79770314的博客 445

论一个程序员的自我修养

本篇文章转载-转瞬之夏   在《喜剧之王》中,周星驰扮演的尹天仇,一直梦想成为一名演员,而他不管是在扮演跑龙套,或者在街坊中开设演员训练班,亦或成为主角时,他对待演员的态度,始终是认真,热爱而又投入的。而那一本他随身携带的书--《演员的自我修养》,尽管不知道里面具体写的是什么,但我猜,他对待演员的态度和行为,就是书中内容显示的。   于是,不禁问了问自己,作为一名程序员,一...

dbc68367的博客 174

码农的自我修养之 软件科学基础概论

码农的自我修养之软件科学基础概论一、软件是什么?软件的基本构成元素对象(Object)函数和变量/常量指令和操作数0和1是什么?软件的基本结构顺序结构分支结构循环结构函数调用框架继承和对象组合软件中的一些特殊机制回调函数多态闭包异步调用匿名函数软件的内在特性 一、软件是什么? 软件的基本构成元素 对象(Object) 一个对象作为某个类的实例,是属性和方法的集合。对象和属性之间有依附关系,属性用来描述对象或存储对象的状态信息,属性也可以是一个对象。对象能够独立存在,对象的创建和销毁显式地或隐式地对应着构造

qq_39411845的博客 2356

从码农到工匠,程序员必备的两本提升自我修养的书

软件设计不仅是“技术”(Technique),更是一门“技艺”(Craftsmanship),要想控制复杂度,防止系统腐化。我们不能只满足做一个搬砖的“码农”,而是要坚持自己的技术梦想和技术信仰,怀有一颗“匠人”之心,保持专注、持续学习,每天进步一点点。唯有如此,我们才有可能“从码农走向工匠”! 程序员必备的两本提升自我修养的两本书: 重构:改善既有代码的设计(第2版) 本书的读者是专业的程序员,也就是那些以写软件为生的人。本书的范例和讨论,涉及大量需要阅读和理解的代码。这些都是用JavaSc

人邮异步社区 1321

码农的自我修养 - 流程图 Flowchart

什么是流程图? 设计和文档化是一个过程,需要将不同的步骤从开始到结束都绘制出来。在这种情况下,一个错误就会导致整个系统崩溃,造成时间、金钱、资本设备的重大损失,甚至可能威胁到执行该过程的人力的安全。因此,构建流程图是为了设计和记录的一种方法。 流程图是一个程序的逻辑步骤顺序的图解表示。流程图使用简单的几何图形来描述过程,用箭头来显示关系和过程/数据流。 流程图是一种描述过程、系统或计算机算法的图表。它们被广泛用于多个领域,以清晰、易懂的图表来记录、研究、计划、改进和沟通通常复杂的过程...

guoqx的专栏 5942

程序员练级攻略:程序员修养

这是一篇转载自陈皓《左耳听风》专栏的文章,这篇文章介绍了要做一名合格的软件工程师,需要具备的修养,注意这里我说的是工程师,而不是码农。 这是程序员的工程师文化,也就是程序员的价值观,因为我觉得如果你的技术修养不够的话,你学再多的知识也是没有用的。 要了解程序员的修养,你可以先从 Quora 上的这个贴子开始 “What are some of the most basic things every programmer should know?”,我摘录一些在这里供你参考。 Bad architec.

Kaybee - 练级之路 727

论程序员的个人修养

小时候多么希望时间能快点啊,让我们能快点长大,去到外面那五彩缤纷、花花绿绿的世界中去啊。长大后,又多么想回到从前,回到从前那个无忧无虑、天真烂漫的童年。 ...

没有了糖的可乐 466
上一篇: 电脑硬盘图标换成自己喜欢的图标
下一篇: CASS软件图廓属性注记内容一般标准(坐标系统、高程系统、图式标准、测制时间)
GeoBase
博客等级 码龄6年 41粉丝 9原创
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值