为什么写注释必须成为编码的硬性标准(双语原创)

为什么写注释必须成为编码的硬性标准(双语原创)

Why Writing Annotation Must Become Peremptory Rule?

程序猿最烦的事:别人的代码不写注释;自己写注释。

Parodox: It is most hated for programmers that others‘code have not annotations, and oneself must write annotations.

1.注释最主要是给别人看的,供自己回顾是锦上添花

理解一个人的思想,尤其是具有深度复杂逻辑的思想,是相当之难的。这也是为何不少科学理论要写洋洋数万言,甚至一本书来解释它。如果这种思想只存在于自己脑子之中,有些人自然不会费那个劲去写,但有些人还是要写。难道是后面的人比前面的人笨吗?绝对不是。我们生活在地球上,同属人类,我们都有人类共同的弱点。人的大脑不是万能的,记忆是会淡漠甚至遗忘的。因为只有淡漠和遗忘才能让大脑高效地工作,去获取新的知识。这道理不言自明。

写代码是什么?我把它定义为用相对抽象的符号,来描述解决问题的方法。所以,它有两个特殊属性:(1)一套完备的逻辑解释;(2)一套相对抽象的表述。所以,掌握这个技术是具有相当难度的,这个星球上能掌握它并能运用好它的人比例很低。程序猿们,你们因为你们的聪明而沾沾喜喜了吗?先别忙高兴。程序猿面临其他人同样的问题:遗忘。有句老话:时间就是把杀猪刀。任你男神女神,都会被时间搞掂。再聪明的大脑也不会例外。

理解抽象的描述本来就费时间,尽管作者可能认为它已经很清晰了。但是过一段时间,不说别人,即便作者自己也可能会忘却当时写下这段逻辑描述的场景。因为程序猿多数时间是为了满足别人的需求而写代码。别人的需求自然是别人的思想。别人的思想被忘掉时,你如何保证你为别人思想所写的抽象描述不被忘掉?神仙也做不到吧。因为神仙是不会陷入自我悖论的。进一步,如果是看你代码的人呢?他(她)可能连当时用户提需求的场景都毫不知晓,他(她)又如何理解你那高深莫测的抽象表述呢?你可能会说:嗯,我是按xxx那种牛x方法写的,足够简单明了,只要你会x语言,你就能看懂。老天爷,你知道你在说什么呢?要知道,人类的智慧连理解别人的自然语言都可能出现歧义,你如何保证被抽象了的表述不会发生这种情况呢?恐怕连那些电脑语言的发明者也不敢这么说吧。这也是为何所有高级语言都保留注释功能。

所以,如果你承认你仍属于人类,请抛开自负和执拗,正视人类的弱点,老老实实写注释吧。



1.Annotation mainly aims to others, then review for yourself

It‘s fairly diffcult to understand a kind of mind of human, especially include sophisticated logic. This is why some science theories were written by a lot of words or book to explain them. If these minds only retain in brains, some people think they would not write them arduously, but others don‘t think so. Is it right the latter more awkward than the former?Certainly it‘s not. We are terrestrial, we are human, we have same weakness. Human‘s brain is not omnipotent. Memory decline so much as vanish. Brains is effectively work to get more new knowledge since declines and vanishes. It‘s well known.

But what‘s the coding? In my definition, it is described a method that solve problem with relatively abstract symbols. So it has two properties: (1)an set of entire explainations; (2)a set of relatively abstract descriptions. It‘s difficult to master the skill for majority of people. The rate to master and steer it smoothly is fairly small. Coding monkeys, are you pleased with yourself? Don‘t celebrate so soon. Programmers face the same problem as others: LETHE. The old saying “Time will kill all”. You must be killed by time, no matter how you are niubility man or lady. It is wise brain that never escape.

It cost more time to understand abstract description, in spite of author thinks it is legible.But after a while, don‘t say others, even author may forget the scene that code at that time.Because programmers usually code for other‘s requirements.Other‘s requirements certainly come from other‘s minds. How do you ensure that abstract descriptions you wrote for other‘s requirement are not forgetten while other‘s minds are forgetten? God can‘t do it. God should not swamp into paradox himself. And then, how about it is others to see your code.He(or She) knew nothing about scene client commited requirements.How did he(or she) understand the unfathomable abstract description you wrote?“Hum, I coded according to niubility method from XXX.If you master X language, you can understand them easily.“, you might say. Oh my God. What did you know what you said? You should know that devergence exist in nature language understanding to be limited human‘s intelligence. How did you ensure it shouldn‘t happen in such abstract description? I‘m afraid creators of these computer languages can‘t say that. That is why all high level computer language reserve annotation function.

So, you should discard ego and pigheadedness if you admit you are human.You must face up to human weakness and write anotation in earnest.



2.注释简化代码理解

有时,你维护一段他人的代码,需要解决其中的bug。这时,你需要通过读懂其他代码来辅助你找到bug。当你确认问题不是其他代码导致时,你仅仅需要明白其他代码的逻辑结构即可,而不必逐字逐句地去读懂。这时,一段注释良好的代码会加快你的工作。甚至你仅仅需要通过读函数或方法的头部说明注释,就可以完成这步工作。毕竟,读懂注释中的自然语言比读懂最清晰明了的代码还是要容易的多。这样的注释对别人如此,对自己何尝不是方便?有什么理由不写它呢?

对接手他人项目的程序猿来说,提纲挈领的注释加快理解整个项目代码,会更快地完成移交工作,对于后来者迅速进入角色,完成催命似的项目经理的要求,是功德无量的事。这就是为何程序猿们对他人不写注释的代码都深恶痛绝的原因。

总之,己所不欲勿施于人。在为他人代码不写注释大肆吐槽之时,认真想想自己做的怎样。你对写注释还有偏见吗?如果没有,恭喜你,你已经接受了这样的硬性规则:所有代码必须写注释。好吧,如何写出提纲挈领、简明扼要的注释超出本文讨论之列。



2.Anotation simplify understanding

Sometimes you must fix bugs in someone‘s code. You need read and understand relative codes to assit you finding bug. When you confirm the reason of bugs not to come from these codes, you just understand logical structure of these codes which not read them word for word and sentance for sentance. It shoud speed up your work at this time. You may end this step through reading head anotation of them even. After all, reading nature language from anotation is much easier than reading the plainest code. The anotation is convenient for others and yourself. What reason should you not write them?

Anotation concentrate on the main point speed up understanding whole project codes for the programmers takeing up other‘s work. It‘s eariler to finish the work takeing up from others. The benifits are beyond that the latter work in role as soon as possible to finish the pressing task from PM. This is why coding monkeys extremely detest the codes have not anotation.

Anyway, do unto others as you would be done. You should consider how do you do seriously when you complain other‘s codes without anotation. Do you have prejudice for writing anotation? If not, congratulations on you, you already accept the following preremptory rule: Any coding and Any anotation. Well, how to write plain anotation concentrate to main point, it is out of range of this article.

*Written by Wayman Qi*
时间: 2024-10-23 19:53:43

为什么写注释必须成为编码的硬性标准(双语原创)的相关文章

给jdk写注释系列之jdk1.6容器(13)-总结篇之Java集合与数据结构

是的,这篇blogs是一个总结篇,最开始的时候我提到过,对于java容器或集合的学习也可以看做是对数据结构的学习与应用.在前面我们分析了很多的java容器,也接触了好多种常用的数据结构,今天我们就来总结下这些内容. 下面我们以数据结构的维度来总结下,在Java集合的实现过程中,底层到底使用了哪些常用的数据结构中,他们分别又有什么特点.      1. 数组(Array) 结构说明:在程序设计中,为了处理方便, 把具有相同类型的若干变量按有序的形式组织起来.这些按序排列的同类数据元素的集合称为数组

给jdk写注释系列之jdk1.6容器(10)-Stack&Vector源码解析

前面我们已经接触过几种数据结构了,有数组.链表.Hash表.红黑树(二叉查询树),今天再来看另外一种数据结构:栈. 什么是栈呢,我就不找它具体的定义了,直接举个例子,栈就相当于一个很窄的木桶,我们往木桶里放东西,往外拿东西时会发现,我们最开始放的东西在最底部,最先拿出来的是刚刚放进去的.所以,栈就是这么一种先进后出( First In Last Out,或者叫后进先出) 的容器,它只有一个口,在这个口放入元素,也在这个口取出元素. 栈最主要了两个动作就是入栈和出栈操作,其实还是很容易的明白的对不

给jdk写注释系列之jdk1.6容器(2)-LinkedList源码解析

LinkedList是基于链表结构的一种List,在分析LinkedList源码前有必要对链表结构进行说明. 1.链表的概念 链表是由一系列非连续的节点组成的存储结构,简单分下类的话,链表又分为单向链表和双向链表,而单向/双向链表又可以分为循环链表和非循环链表,下面简单就这四种链表进行图解说明.           1.1.单向链表 单向链表就是通过每个结点的指针指向下一个结点从而链接起来的结构,最后一个节点的next指向null.      1. 2.单向循环链表           单向循环

给jdk写注释系列之jdk1.6容器(12)-PriorityQueue源码解析

PriorityQueue是一种什么样的容器呢?看过前面的几个jdk容器分析的话,看到Queue这个单词你一定会,哦~这是一种队列.是的,PriorityQueue是一种队列,但是它又是一种什么样的队列呢?它具有着什么样的特点呢?它的底层实现方式又是怎么样的呢?我们一起来看一下. PriorityQueue其实是一个优先队列,什么是优先队列呢?这和我们前面讲的先进先出(First In First Out )的队列的区别在于,优先队列每次出队的元素都是优先级最高的元素.那么怎么确定哪一个元素的优

给jdk写注释系列之jdk1.6容器(6)-HashSet源码解析&Map迭代器

今天的主角是HashSet,Set是什么东东,当然也是一种java容器了. 现在再看到Hash心底里有没有会心一笑呢,这里不再赘述hash的概念原理等一大堆东西了(不懂得需要先回去看下HashMap了),需要在啰嗦一句的是hash表是基于快速存取的角度设计的,也是一种典型的空间换时间的做法(这个在分析HashMap中都有讲过).那么今天的HashSet它又是怎么一回事的,他的存在又是为了解决什么问题呢? 先来看下Set的特点:Set元素无顺序,且元素不可以重复. .想到了什么?无顺序,由于散列的

关于SVNcommit时强制写注释方法

关于SVNcommit时强制写注释方法 一.摘要 场景: 在这次开发项目过程中,团队中总是有人忘记添加注释. 问题: 1:其他成员不知道你提交是什么代码, 给回滚操作带来很多不必要的麻烦. 2:这个工作需要有一个人天天提醒大家在提交代码的时候加入注释. 3:这个是重复的,定时的,固定的 工作. 思路: 1:我们可以把这项工作交给电脑来完成岂不是更好. 2:提交代码的时候电脑自动提醒. 3:代码注释字数限制.以下为最少5个字为例子. 二.本文大纲 a.摘要. b.本文大纲. c.第一步创建SVN版

给jdk写注释系列之jdk1.6容器(1):ArrayList源码解析

原文出自吞噬天地,链接整理自ImportNew 给jdk写注释系列之jdk1.6容器(2):LinkedList源码解析 给jdk写注释系列之jdk1.6容器(3):Iterator设计模式 给jdk写注释系列之jdk1.6容器(4)-HashMap源码解析 给jdk写注释系列之jdk1.6容器(5)-LinkedHashMap源码解析 给jdk写注释系列之jdk1.6容器(6)-HashSet源码解析&Map迭代器 给jdk写注释系列之jdk1.6容器(1):ArrayList源码解析 工作中

写算法题的时候怎么写注释

比较好的写注释方式:先写出大部分注释,再开始写算法代码(如果你采用的就是这种方式,那么恭喜你,你已经学会了,可以完全不看这篇文章,因为下面都是陈述这种方式能带来的好处以及用其他方式的缺点,如果你采用的不是这种注释方式,那么建议你浏览一下这篇文章,说不定会提升你的编码效率) 一般在看到算法题都会先在脑子中想出一个大概的思路,而注释就是记录这个思路的大概内容,注释可以帮我们进一步理清思路,可以使我们的代码更加模块化,每一步的代码功能更加明显.注释最主要的功能还是给自己提示,因为我们在实现上一个部分的

写个js动态调整图片宽高 (原创)

<body style="TEXT-ALIGN: center;"> <div id="testID" style="background:red;MARGIN-RIGHT: auto; MARGIN-LEFT: auto; width:173;height:184"> <img src="http://e.hiphotos.baidu.com/image/pic/item/024f78f0f736afc3