发表于：2019/7/24 19:19:48
#0楼
【万泉河】PLC编程：注释有多重要？
经常在各种场合见过一些行业专家整理的PLC编程的技巧或者原则，经常其中总会有一条：完备的注释。
我自己也发起过好程序差程序的讨论，见文章《【万泉河】好的PLC程序和坏的PLC程序的比较标准》
http://www.ad.siemens.com.cn/club/bbs/PostStory.aspx?a_id=1479565&b_id=82&s_id=&num=174#anch
后面的跟贴的网友，就有不少把完备的注释作为一个主要条件补充在后面的。大意就是写上完备注释的才是好程序，不写注释的就是烂程序！一看就知道是以往被没有详尽注释害惨了。简直苦大仇深啊！
看到这些评论的时候，我总是微微一笑。
不接茬。
今天主动讨论一下这个话题。
先说下什么是注释，为什么要写注释。
显然，符号表变量名不是注释。注释是程序段之间，或者每个程序段开头，留白的区域，可以备注一些文本。这些文本不是程序的一部分，所以没有语法检查，也不会报错。现在的软件，普遍已经支持中文注释了。不会有任何问题。
换位思考下，为什么要写注释？是编程者自己的备忘录。写给自己，或者自己团队其他人的。比如工作将来有可能交由其他同事继续完成或者维护，那么在这里把当时的想法，做法，改动细节等等记录下来。将来再有问题的时候，后来者可以从中了解到一些重要参考信息。
所以总的来说，注释是写给自己的。
如果注释的目标读者是其它人，比如学生。那么这是学校老师在准备教学生学习编程的教材。因为学生对象的认知水平是固定的，所以可以有的放矢的来写。
而如果目标读者都是未知的，这注释可怎么写？从最基础的一步步写还是步子大一点直接写最精要的纲领？
写的太精炼了，初学者就会表示看不懂，就有可能抱怨你注释没写好。甚至有情商低的，会从中揣度出来阴谋论，认为你就是故意不好好写注释，就是为了...让...俺...们...看...不...懂...！
而你要是注释写的每个细节面面俱到，那除了初学者之外的高手，或者初学者过了初学阶段后，看到这些注释，会认为罗嗦，你写这么详细，是拿我们当幼儿园小朋友吗？啥都往里面写，没有主次，重点都沉没在垃圾信息里了！
所以，标准都很难定呢！
我在初学PLC的时候，那时候还是S5的PLC，读的老外的程序，关于指示灯的。大致是：
意思是系统运行的时候指示灯亮起。但系统运行过程中（不会停），如果有不正常的状况，就闪烁。
那时候就非常搞不懂，一个运行，一个闪烁，并联就是了。为啥还要多此一举在运行后面还串个ALARM的非？
也抱怨过老外程序的注释也不写明白点。当然啦，他就是写的那点注释，也是德语的。要看懂还得逐字查德语词典。
后来，等自己写程序的时候，就下定决心，一定要让后面的维护人员看得懂！所以事无巨细，各种说明都写的满满的。
可这一行逻辑这样，换个设备还是这个逻辑，就把它连程序带注释复制过来，反正也不累。等复制上二十几行，我就想，我是不是成了絮叨的老太婆了？人家看了会不会烦啊！
那么程序的注释到底应该写成啥样子呢？
其实在论坛讨论的回帖里面，就有人说过，好的程序自带注释。
深以为然。
看一下标准化架构下做的一段程序吧，一个设备的调用：
这样的程序，连注释都是多余的。
但换个视图，不显示符号，只显示绝对地址会怎样？
乱糟糟，完全看不懂啊！每个变量都做啥的？
所以，我们的程序，需要的是一套完备的符号表，以及详尽的库函数的接口描述和功能说明。简单设备的库函数也不需要。
总结一句话：好的程序架构自带注释功能。
经常在各种场合见过一些行业专家整理的PLC编程的技巧或者原则，经常其中总会有一条：完备的注释。
我自己也发起过好程序差程序的讨论，见文章《【万泉河】好的PLC程序和坏的PLC程序的比较标准》
http://www.ad.siemens.com.cn/club/bbs/PostStory.aspx?a_id=1479565&b_id=82&s_id=&num=174#anch
后面的跟贴的网友，就有不少把完备的注释作为一个主要条件补充在后面的。大意就是写上完备注释的才是好程序，不写注释的就是烂程序！一看就知道是以往被没有详尽注释害惨了。简直苦大仇深啊！
看到这些评论的时候，我总是微微一笑。
不接茬。
今天主动讨论一下这个话题。
先说下什么是注释，为什么要写注释。
显然，符号表变量名不是注释。注释是程序段之间，或者每个程序段开头，留白的区域，可以备注一些文本。这些文本不是程序的一部分，所以没有语法检查，也不会报错。现在的软件，普遍已经支持中文注释了。不会有任何问题。
换位思考下，为什么要写注释？是编程者自己的备忘录。写给自己，或者自己团队其他人的。比如工作将来有可能交由其他同事继续完成或者维护，那么在这里把当时的想法，做法，改动细节等等记录下来。将来再有问题的时候，后来者可以从中了解到一些重要参考信息。
所以总的来说，注释是写给自己的。
如果注释的目标读者是其它人，比如学生。那么这是学校老师在准备教学生学习编程的教材。因为学生对象的认知水平是固定的，所以可以有的放矢的来写。
而如果目标读者都是未知的，这注释可怎么写？从最基础的一步步写还是步子大一点直接写最精要的纲领？
写的太精炼了，初学者就会表示看不懂，就有可能抱怨你注释没写好。甚至有情商低的，会从中揣度出来阴谋论，认为你就是故意不好好写注释，就是为了...让...俺...们...看...不...懂...！
而你要是注释写的每个细节面面俱到，那除了初学者之外的高手，或者初学者过了初学阶段后，看到这些注释，会认为罗嗦，你写这么详细，是拿我们当幼儿园小朋友吗？啥都往里面写，没有主次，重点都沉没在垃圾信息里了！
所以，标准都很难定呢！
我在初学PLC的时候，那时候还是S5的PLC，读的老外的程序，关于指示灯的。大致是：
意思是系统运行的时候指示灯亮起。但系统运行过程中（不会停），如果有不正常的状况，就闪烁。
那时候就非常搞不懂，一个运行，一个闪烁，并联就是了。为啥还要多此一举在运行后面还串个ALARM的非？
也抱怨过老外程序的注释也不写明白点。当然啦，他就是写的那点注释，也是德语的。要看懂还得逐字查德语词典。
后来，等自己写程序的时候，就下定决心，一定要让后面的维护人员看得懂！所以事无巨细，各种说明都写的满满的。
可这一行逻辑这样，换个设备还是这个逻辑，就把它连程序带注释复制过来，反正也不累。等复制上二十几行，我就想，我是不是成了絮叨的老太婆了？人家看了会不会烦啊！
那么程序的注释到底应该写成啥样子呢？
其实在论坛讨论的回帖里面，就有人说过，好的程序自带注释。
深以为然。
看一下标准化架构下做的一段程序吧，一个设备的调用：
这样的程序，连注释都是多余的。
但换个视图，不显示符号，只显示绝对地址会怎样？
乱糟糟，完全看不懂啊！每个变量都做啥的？
所以，我们的程序，需要的是一套完备的符号表，以及详尽的库函数的接口描述和功能说明。简单设备的库函数也不需要。
总结一句话：好的程序架构自带注释功能。
[此贴子已经被作者于2019/7/25 8:07:16编辑过]
PLC标准化编程
