电子技术论坛_中国专业的电子工程师学习交流社区-中电网技术论坛

标题: 更佳编程之路第二章注释代码-1 [打印本页]

作者: look_w 时间: 2018-4-15 20:21 标题: 更佳编程之路第二章注释代码-1

基本注释编写程序时，使用良好的规划。不必事先确定每个细节，但是应该将程序分成几个组成部分，并且使用注释来填充间隙。
下列是我个人的编码风格。您可能不喜欢它，但是请客观地看待它，并且看看有什么可以为您及您的团队所用。
首先，考虑一下该注释的预期读者。尽量使注释足够清晰，以便第三方顾问领会。代码越复杂，就应该添加越多的注释以阐明目的。不要将注释放在以后再做；让它们成为您思考过程的一部分：问题、解决方案、注释，然后调试。在调试之前创建注释尤为重要。您自己代码中的注释将有助于更好和更快地调试。
有时不仅陈述问题的解决方案很有帮助，而且陈述问题本身也是很有帮助的。例如：
清单 1

1
2
3
4
5
6
7
8
9
10

# function: do_hosts
#
# purpose: to process every host in the /etc/hosts table and see if it
# resolves to a valid IP
#
# solution: read the list of hosts as keys in a hash, then go through
# the list of keys (hosts) and store the IP address for each host as
# the value for that key, or undef() if it doesn't resolve properly.
# Return a reference to the hash, or undef if the /etc/hosts file was
# not accessible.

推荐简化为：
清单 2

1
2
3
4
5

# function: do_hosts: process every host in the /etc/hosts table and
see if it
# resolves to a valid IP; return a reference to the hash (key=host,
# value=IP or undef), or undef if the /etc/hosts file was not
accessible.

还有另一种方法：
清单 3

1 2	# do_hosts: returns a ref to hash of hosts (key=host, value=IP/undef) # from /etc/hosts

以上方法都有效，这取决于 do_hosts() 的复杂程度。如果函数只有两行，则不要浪费时间来写三段注释。但是，如果函数有几页，则不要吝惜说明。
注释程序的开头程序应该以对其目的简要说明来开头。不要让人们滚动几页才能弄清您在做什么。如果正在使用版本控制系统（例如，CVS），则将适当的头（例如，ID头）放在文件的开头。尽量简练。两行，最多四行，应该足以对程序进行简要描述。给出联系人姓名、电子邮件、电话号码或团队联系方式。
清单 4

1
2
3
4

#!/usr/bin/perl -w
# whodunit.pl: A script to solve a murder mystery
# by joe@shmoe.com $Id: whodunit.pl,v 1.92 2000/08/08 19:08:50 joe Exp
$

第一行上的注释是大多数 UNIX系统上的一种标准方法，用来表示执行脚本时运行哪一个应用程序（在“!”后的所有东西被认为是解释器名称）。-w标志表示打开警告标志 —总是一个很好的主意，即使对于很有经验的程序员来说。
第二行（第一个注释行）是程序及其目的的简短描述。第三行（第二个注释行）给出了作者姓名和唯一标识文件的发布日期和版本的ID 头。RCS 和 CVS 特别地使用 ID 头，它在提交脚本时自动更新。有关RCS 和 CVS 的更多信息，请参阅本文后面的。
注释初始化节初始化节应该在逻辑上和物理上与程序的开头分开，例如，可以通过额外注释或让它处于文件的开头来实现。初始化节，与上面描述的程序的开头相反，包含程序启动时执行的实际代码。在Perl 中，初始化节应该由下列部分组成（最好按该顺序）：

模块和编译指示
常量
BEGIN/END/INIT/CHECK 子例程
初始化代码

模块和编译指示Perl 中的 use 关键字命令解释器装入模块或者打开编译指示（“nopragma”关闭编译指示）。编译指示将解释器引入正确的方向。例如， use utf8 告诉解释器要准备好 UTF-8 编码的数据文件和流。
使每个模块的注释在水平方向上排列整齐，并且每个模块或编译指示有一个注释，是大有好处的。
清单 5

1
2
3
4

use Data:

umper;             # for debugging printouts
use strict;                   # be strict - pragma for the
interpreter
use POSIX;                   # use the POSIX functions

第一次这样做时，只需要复制和粘贴就可以将模块和编译指示放入新程序。我建议“strict”编译指示。此外，它还将确保您诚实地声明变量，以我的经验，这是Perl 中的错误源，就象内存分配是 C/C++ 中的错误源一样。
请使用 perldoc命令来察看所有模块和编译指示文档。例如， perldoc strict 说明了有关 strict 编译指示的所有信息 —它可以做什么，如何使用，等。
某些编辑器具有总是将注释放在特定位置的良好能力（在 Emacs中，indent-for-comment命令自动完成该操作）。您自己应该彻底熟悉编辑器的命令。这值得花时间。
常量虽然可以作为另一个 Perl编译指示来查看常量，但是它们应该有自己的节。它们的注释应该类似于模块和编译指示的注释，但是，如果将箭头对齐，将更好看：
清单 6

1
2
3
4
5
6

use constant ALPHA => 1; # alpha code
use constant BETA    => 2; # beta code
use constant GAMMA => 3; # gamma code
use constant USER    => 4; # user ID offset
use constant GROUP => 5; # group ID offset
use constant DEPT    => 6; # dept. ID offset

BEGIN/END/INIT/CHECK子例程象注释常规子例程一样注释 BEGIN/END/INIT/CHECK子例程（有关更多信息，请参阅 perldocperlmod ）。在文件的任何位置都可以创建它们，并且有可能多次定义它们。我建议将它们放在文件的开头或结尾，这样易于找到它们。请注意只有一行的BEGIN 函数不需要详尽的注释。
清单 7

1
2
3
4
5
6

# BEGIN: executed at startup, assigns 'root' to the USER environment
variable
BEGIN
{
$ENV{USER} = 'root';
}

初始化代码实际代码出现在初始化节的最后。同样，如果可能，在单个块中将注释对齐。
清单 8

1
2
3
4
5
6
7
8
9
10
11
12
13
14

$| = 1;
# auto-flush the output
$Data:

umper::Terse = 1; # produce human-readable
Data:

umper output
# define the configuration variables
my $config = AppConfig->new();
$config->define(
            # list of undo commands
            'UNDO'          => { ARGCOUNT => ARGCOUNT_LIST },
            # file to log data
            'LOG_FILE'       => { ARGCOUNT => ARGCOUNT_ONE  },
            );
$config->file(whodunit.conf');       # load the whodunit
configuration file

初始化代码打开自动刷新（auto-flushing）显示（因此，将立即显示输出），然后告诉 Data:

umper 模块产生可读的输出，最后创建 AppConfig配置。

欢迎光临电子技术论坛_中国专业的电子工程师学习交流社区-中电网技术论坛 (http://bbs.eccn.com/)