Style Guidelines for Assembly Language Programmers
汇编程序员之代码风格指南


作者：Randall Hyde
[URL=http://webster.cs.ucr.edu/]http://webster.cs.ucr.edu/[/URL]
译者：jhkdiy
[URL=http://jhkdiy.icpcn.com]http://jhkdiy.icpcn.com[/URL] or [URL=http://www.20cn.net]http://www.20cn.net[/URL]
e-mail:jhkdiy_gzb@21cn.net
译期：开始于06年7月4号。结束于8月31日
原文总页数：42页。译文总页数：60页。


大家知道这位作者吗？不知道？晕••••。那看过《The Art of Assembly Language》一书吗？该书的作者就是Randall Hyde。
这本书在国外有很高的评价，以至于国内也有了翻译的版本：《汇编语言编程艺术》。由陈曙晖翻译，我买了但还没看^_^!。这份代码风格指南是我在作者主页里找到的，有空就去浏缆一下吧，或许有意外收获哦！
在这漫长的翻译旅途中，自己也是一边翻译一边学习该文档的。翻译完后觉得要写出一个易读的程序其实并不容易，但也不是很难，只要自己坚持遵循该文档的话就可以尽能地做到程序易读了。自己学习汇编语言也有一段时间了，却很少在网上的论坛见到过非常易读的汇编程序，绝大一部分是没有任何注释、带有一大堆a、b、d等变量名的难读程序，有一次看到有人特意将整个C语言源代码改成像文字画一样我就跟他吵了起来。无论是汇编也好、C语言或其它语言也好，很多编程的朋友都不把代码的易读性放在眼里，有的甚至从来不考虑，只要代码能执行起来，程序运行起来就算完事了。更有的程序员为编写难读的代码而自我臭美。而大学里教授编程语言的时候，很少有老师对程序的易读性做过教导或建议，以至于学生们从一开始便没有编写易读代码的意识，这在一定程度上增加了编写难读程序的人员。代码是拿来读的，为了能更快更容易地阅读代码，我们必定要遵循一定的规则。
我真心希望越来越多的朋友能写出可读性好的代码，就算将代码发表到全世界，只要学过该语言的人都能看懂中国人编写的程序，因为它深具可读性，读代码像读诗篇一样流畅而自然。希望这一天早日到来！
jhkdiy
2006-8-31


《汇编程序员之代码风格指南》

目录：

1.0简介

1.1 ADDHEX.ASM

1.2 Graphics Example

1.3 S.COM 例子

1.4本文面向的读者

1.5可读性标准

1.6怎样做到可读性

1.7这份文档的组织

1.8指导、 规则、强制性规则、和例外

1.9 涉及的语言

2.0程序组织

2.1库函数

2.2公共目标模块

2.3局部模块

2.4程序的make文件

3.0 模块组织

3.1模块属性

3.1.1模块内聚性

3.1.2模块耦合性

3.1.3模块的物理组织

3.1.4模块接口

4.0程序单元组织

4.1例程内聚性

4.1.1例程耦合性

4.1.2例程大小

4.2主过程和数据的安排

5.0语句组织

6.0注释

6.1什么是一个坏注释？

6.2什么是一个好注释？

6.3行终止注释VS独立注释

6.4未完成的代码

6.5代码交叉参考到其它文档

7.0名称、指令、操作数和操作

7.1名称

7.1.1命名约定

7.1.2字母大小写考虑

7.1.3缩略语

7.1.4标志符内的成分位置

7.1.5要避免的名称

7.2指令、伪指令和伪操作码

7.2.1选择最好的指令序列

7.2.2控制结构

7.2.3同意义的指令



8.0数据类型

8.1用TYPEDEF定义新的数据类型

8.2创建数组类型

8.3在汇编语言里声明结构体

8.4数据类型的UCR标准库




因该网站使用了防止盗链技术，请下载文件的朋友使用下载工具进行下载，切勿使用右键另存为！

[URL=http://jhkdiy.go3.icpcn.com/file/download/AsmCodeStyleCN.pdf]
高清晰PDF文件下载
[/URL]

节选1.0 和 1.1：
1.0简介
许多人认为汇编程序难于阅读。虽然大家有这种感觉有许多原因，但最主要的还是汇编语言难以使得程序员写出易读的程序。这并不表示不可能编写出易读的程序，只是它要花费汇编程序员一部分额外的工作来写出易读代码。
为了示范汇编程序的一些公共问题，决定使用下面的程序或程序段。这些都是在Internet上找到的真正用汇编语言编写的程序。每个例子都示范了一个单独的问题。（顺便一提：选择这些程序并不是有意让原作者难吭。这些程序都是在网上找到的汇编代码特例）。

[CODE]
1.1ADDHEX.ASM
%TITLE "两个16进制数相加"
IDEAL
DOSSEG
MODEL small
STACK 256
DATASEG
exitCode db 0
prompt1 db 'Enter value 1: ', 0
prompt2 db 'Enter value 2: ', 0
string db 20 DUP (?)
CODESEG
EXTRN StrLength:proc
EXTRN StrWrite:proc, StrRead:proc, NewLine:proc
EXTRN AscToBin:proc, BinToAscHex:proc
Start:
mov ax,@data
mov ds,ax
mov es,ax
mov di, offset prompt1
call GetValue
push ax
mov di, offset prompt2
call GetValue
pop bx
add ax,bx
mov cx,4
mov di, offset string


call BinToAscHex
call StrWrite
Exit:
mov ah,04Ch
mov al,[exitCode]
int 21h
PROC GetValue
call StrWrite
mov di, offset string
mov cl,4
call StrRead
call NewLine
call StrLength
mov bx,cx
mov [word bx + di], 'h'
call AscToBin
ret
ENDP GetValue
END Start
[/CODE]
好了，这个程序的最大问题还是相当明显的－除了标题之外完全没有其它注释（译注：国内有太多这样没注释的程序了）。另一个实际的问题则是用来提示用户的字符串出现在程序的一端但用来打印这些字符串的调用代码却出现在另外一个地方（译注：即指代码中的StrWrite等三个函数）。尽管这是个经典的汇编语言编程方法，但却导致了代码难于阅读。另外，相对次要的一个问题是该程序使用了TASM的 “less-than”IDEAL
语法（注：一些一直使用TASM的人会认为这没什么不好。但个别人就不这么认为了，由于他们不熟悉TASM的古怪语言，有时会导致被程序中的几条语句搞混淆）
这个程序也使用了MASM/TASM的“简单化”段定义。微软声称的这个典型特性却给一个“简单”的工程增加了复杂性。如果该程序转换为标准的段定义格式将会更加易读。
（注：使用简单段定义虽然更容易编写高级语言接口的汇编程序，但无论如何，他们都只会使单一的程序问题变得复杂）
在扔掉它之前，该程序还是有两点值得称赞的（遵循了可读性）。第一，该程序员为过程名和本程序使用的变量选择了一组合理的名称（我假定这段代码的作者同时也是该程序调用的库的作者）。程序另一个值得肯定的是助记性好和操作数之间有良好的对齐。
OK，在抱怨这份代码如何难读后，为什么不来个更易读的版本？下面的程序便是，可证明，该版本比上面的版本更加易读。可证明，因为该版本使用了UCR标准库v2.O
并假定读者熟悉该库的细节和特性。
[CODE]
;**************************************************
;
; AddHex-
;
; 这个简单的程序从用户那里获取两个整数值，计算它们的和，
; 并在屏幕上打印结果。
;
; 这个例子使用了“80x86汇编程序员的UCR标准库v2.0”
;
; Randall Hyde
; 12/13/96
title AddHex
.xlist
include ucrlib.a
includelib ucrlib.lib
.list
cseg segment para public 'code'
assume cs:cseg
; GetInt-
;
; 这个函数从键盘读取一个整数并将结果返回到AX寄存器中
;
; 该程序捕获无效的值（太大或无效数字）并需要用户重新输入一个数值。
;

GetInt textequ <call GetInt_p>
GetInt_p proc
push dx ;DX 保存错误代码
GetIntLoop: mov dx, false ;假定没错误
try ;捕获任何可能的错误
FlushGetc ;清空输入来换新行
geti ;读入整数值
except $Conversion ;捕获错误字符
print "Illegal numeric conversion, please re-enter", nl
mov dx, true

except $Overflow ;捕获数值太大
print "Value out of range, please re-enter.",nl
mov dx, true
endtry
cmp dx, true
je GetIntLoop
pop dx
ret
GetInt_p endp

Main proc
InitExcept
print 'Enter value 1: '
GetInt
mov bx, ax
print 'Enter value 2: '
GetInt
print cr, lf, 'The sum of the two values is '
add ax, bx
puti
putcr
Quit: CleanUpEx
ExitPgm ;退出程序的DOS宏
Main endp

cseg ends

sseg segment para stack 'stack'
stk db 256 dup (?)
sseg ends


zzzzzzseg segment para public 'zzzzzz'
LastBytes db 16 dup (?)
zzzzzzseg ends
end Main

[/CODE]




这里要特别指出的是这份代码比原来的那个AddHex程序要大一点。在细节上，它验证用户的输入；而在原程序上并没有这么做。如果那位想更严密地模范原程序，下面的简单代码即是：
[CODE]
print nl, 'Enter value 1: '
Geti
mov bx, ax
print nl, 'Enter value 2: '
Geti
add ax, bx
putcr
puti
putcr
[/CODE]
在这个例子中，两个简单的解决方案改良了程序的可读性：增加注释、将程序格式化得更好点，而且使用了UCR标准库的高级特性来使得编码更为简单并使得打印输出字符串的语句保持它们的字面意思。

主要讲masm。