程序代码注释的探讨[未完待续]
2007-01-12 00:19
253 查看
在计算机学院学习已经五六年了,在学习理论和编写程序的时候会对一些遇到的问题进行思考,同时也希望和更多有丰富经验的同仁一起探讨。近来在完成一个面向对象课程的程序设计过程中,自己在代码中添加了大量的注释信息,然而在整个设计完成之后,回头再来回顾或修改自己的程序时发现这些注释没有给自己提供有效的信息,对于日后重新分析、理解和修改没有起到应有的提示作用。在网上搜索相关的规范和经验文章时,收获并不是很多,因此将自己遇到的问题和随后的思考与大家共同讨论,希望能够有更多的朋友关注并重视注释的重要意义,科学合理地运用代码注释。
(1)注释的稠密程度:本人以往的程序注释都十分具体和详细,每条语句都附有注释。问题是注释只是描述性语言,与上下文缺乏连贯性,主要为本条语句的语法描述。这样对于查阅代码的人来说几乎没有提供有用的信息,因为阅读代码的人都懂得语句的语法含义,他需要的是这些连贯语句之间的关系和产生的算法特点。因此注释的多与少不是关键问题,提供有效信息才是注释核心目的,而且过多的注释会令代码界面凌乱,是读者难以在其中寻找到所关心的重要信息。
(2)注释的形式:虽然各种语言都有各自的注释方式和语法规范,然而如何组织自己的信息以最有效地方式呈现在阅读者面前并不是一件容易的事情,体现了编写者的智慧和能力。因此我期望寻求一种较清晰明确的信息整合格式。
[A]在程序代码的开头提供必要的整体代码的概括描述和作者的信息。以C++为例:
/*********************************************************
*整个项目的名称和版本信息 *
*本文件在项目中的角色、主要的功能、开发时间以及版本信息 *
*开发者的信息,联系方式 *
*********************************************************/
在这里突出强调一个文件所代表的部分在整个项目工程中的角色和所用。
[b]关于函数的功能描述和使用方法说明。
/************************************************************
*函数的名称,参数以及返回值说明 *
*函数的功能,调用方式和使用说明(与其它函数之间的相互关系)*
************************************************************/
这里突出强调使用函数的方式和注意事项。在何种情况下调用,产生何种结果。
(3)注释的内容:如上文所说的,如果注释只是进行本条语句的语法描述,那么它存在的意义就会大打折扣,毕竟从这些注释中,我们还是很难把握整体代码的逻辑关系和主体思路。将自己的设计思想融入注释中将有助于别人更容易地理解自己的程序。
相关文章推荐
- CSLA.Net 3.0.5 版本 教学程序,代码附教学注释
- 在Linux中#!/usr/bin/python之后把后面的代码当成程序来执行。 但是在windows中用IDLE编程的话#后面的都是注释,之后的代码都被当成文本了。 该怎么样才能解决这个问题呢?
- CSLA.Net 3.0.5 版本 教学程序,代码附教学注释
- 随堂笔记第一天:环境变量配置,代码的三种注释方法,第一个程序,基本数据类型------1
- 把C/C++程序代码中的注释去掉,并返回结果
- 如何将eclipse的程序代码和注释字体变大
- CSLA.Net 3.0.5 版本 教学程序,代码附教学注释
- 计算java文件有多少行注释行,正常代码行,空白行的程序,swing做的
- 从Java代码实现角度探讨CSRF(未完待续)
- 自动添加VS 2008 代码文件版权信息 注释,用小程序实现更改
- CSLA.Net 3.0.5 版本 教学程序,代码附教学注释
- Android进阶#(7/12)装点程序“门面”——代码规范_注释
- 我的程序(4):C++代码注释分离
- 命令行编译android程序,欢迎探讨命令行如何使用proguard混淆优化代码
- 《程序员面试宝典》移除C/C++程序代码中的注释
- CSLA.Net 3.0.5 版本 教学程序,代码附教学注释
- 为代码自动添加注释,让Java程序的阅读和开发更高效
- 汇编写的贪吃蛇的程序(别人写的,我把注释全部写上了,下次我重写一个代码更简洁的)
- 安卓ListView一个简单代码的注释和探讨
- Python Show-Me-the-Code 第 0007 题 统计代码行数(注释,空行,总行数)小程序