注释和格式化代码

An important part of coding is documentation and code formatting, or “programming etiquette” as it may be called.编码的一个重要部分是注释和代码格式化，或者称为“编程礼仪”。The ability of an individual to take written code, decipher its meaning, debug errors, and modify the code for future alternate use is often highly dependent upon the code documentation and format.一个人取得书面代码、解释其含义、调试错误和修改代码以供将来备用使用的能力通常高度依赖于代码注释和格式。

1 .Documenting Code1.注释代码

SAS has two specific features for documenting code: single-line documentation and multi-line documentation.SAS有两个特定的功能来注释代码：单行注释和多行注释。For single line documentation, a statement begins with an asterisk ( ∗ ) and ends with a semicolon.对于单行文件，声明开头星号（*），并以分号结束。Everything contained within such a statement is not considered executable code and is essentially ignored by the compiler, thus serving as notation to the program user. 这种语句中包含的所有内容都不被视为可执行代码，并且实质上被编译器忽略，因此用作程序用户的符号。Multi-line documentation occurs when the statements are offset with / ∗当语句与偏移发生多行的文件/ *and ∗ / (forward slash and asterisk).和* /（斜线和星号）。Everything within those markers is ignored by the compiler.这些标记内的所有内容都被编译器忽略。Multi-line documentation is used when multiple lines of documentation appear together.当多行注释一起出现时，使用多行注释。It does not require the user to include an asterisk at the beginning and a semicolon at the end of each documentation statement.它不要求用户在开头包含星号，在每个注释语句的末尾都包含分号。

Example 3.10 – Single- and multi-line documentation: 示例3.10 - 单行和多行注释：

The following code appears in Example 1.10.以下代码显示在示例1.10中。It appears again here to demonstrate the concepts of single- and multi-line documentation.这里再次出现以演示单行和多行注释的概念。Because the purpose of this example is to demonstrate the documentation, the output is not provided, but can be had in Example 1.10.因为此示例的目的是演示注释，所以不提供输出，但可以在示例1.10中使用。

DATA class_b;

FILENAME inclass ’a:\class data\class b.txt’;

INFILE inclass MISSOVER;

INPUT student $ score;

RUN;

PROC IML;

USE class_b; * opens the data set CLASS_B for use;

READ ALL VAR {student} INTO students;

READ ALL VAR {score} INTO scores;

CLOSE class_b; * closes the data set CLASS_B;

PRINT students scores; ** prints newly-created column

vectors **;

QUIT;

Prior to executable code, the section之前的可执行代码，该节

/ ************************************************* * /

/ **单一和多行注释示例** /

/ ************************************************* * /

gives a title to the program that is easily seen as it is surrounded by many asterisks.给了程序的标题，很容易看到它被许多星号包围。

This provides an example of one use of the multi-line documentation—offsetting a title.这提供了一个使用多行注释 - 偏移标题的示例。It is good practice to include a title or description of a program for future use.优良作法是包括节目的标题或描述以供将来使用。

A researcher whose programs look very similar may have trouble distinguishing programs simply by the file name when wanting to find previously-written code for a future application.程序看起来非常相似的研究人员在想要找到以前为未来应用程序编写的代码时可能会遇到区别程序简单的文件名。

The statements provide another example of how multi-line documentation may be used. 这些语句提供了如何使用多行注释的另一个示例。

The statements * /

demonstrate a method for skipping the execution of a section of code within a program.演示了跳过程序中一段代码执行的方法。

In addition to creating comments, multi-line documentation methods can be used to prevent code from compiling without deleting the code. 除了创建注释，多行注释方法可以用来防止代码编译，而不删除代码。All code within the markers / ∗ 标记内的所有代码/ *and ∗ / are skipped by the compiler when the program is executed. 和 * /是由编译器执行程序时跳过。A use for this is debugging code. 一个用途是调试代码。

The statement该语句

* opens the data set CLASS_B for use;

demonstrates a basic use of single-line documentation. 演示了单行注释的基本使用。 It follows the它紧随

USE class_b; USE class_b;

statement on the same line.语句在同一行。Because the single-line documentation begins with an asterisk and ends with a semi-colon, it is not considered code by the compiler.因为单行注释以星号开头，以分号结尾，所以编译器不会将其视为代码。

The documentation could have also appeared on a separate line of the code.注释也可能出现在代码的单独行。The statementThe statement

该语句

** prints newly-created column vectors **;demonstrates that a combination of asterisks can be creatively used make the documentation stand out more in the code.

演示了星号的组合可以创造性地使用，使注释在代码中更突出。

2 .Use of Case and Spacing2.使用大小写和间距

Programs can include dozens of lines of code. 程序可以包括几十行代码。 Working with dozens of lines of code can be difficult. 使用几十行代码可能很困难。 It can be difficult to identify the beginnings and endings of PROC and DATA steps, nested loop boundaries, etc. It can be difficult to distinguish variable names from functions.可能难以识别PROC和DATA步骤的开始和结束，嵌套循环边界等。可能难以区分变量名称和函数。The use of case and spacing can help organize code so that it is easier to read and manage. 使用大小写和间距可以帮助组织代码，使其更易于阅读和管理。Vertical spacing can be used to separate PROC and DATA steps.垂直间距可用于分离PROC和DATA步骤。Horizontal spacing can be used to identify beginnings and endings水平间距可用于识别循环的起点和终点of loops.。 Using all capital-letters for built-in SAS functions and designations and all lower-case letters for variable names can help distinguish the two.使用所有大写字母的内置SAS函数和指定和所有小写字母的变量名称可以帮助区分两者。

Example 3.11 – Use of case and spacing:示例3.11 - 大小写和间距的使用：

The following two examples show the code from the previous example. 以下两个示例显示了上一个示例的代码。The second set of code shows the use of case and spacing and the first set of code does not.

第一组代码不使用大小写和间距。

data class_b;

filename inclass ’a:\class data\class b.txt’;

infile inclass missover;

input student $ score;

run;

proc print data=class_b;

run;

proc iml;

use class_b;

read all var {student} into students;

read all var {score} into scores;

close class_b;

print students scores;

quit;

第二组代码显示使用大小写和间距，

DATA class_b;

FILENAME inclass ’a:\class data\class b.txt’;

INFILE inclass MISSOVER;

INPUT student $ score;

RUN;

PROC PRINT DATA=class_b;

RUN;

PROC IML;

USE class_b;

READ ALL VAR {student} INTO students;

READ ALL VAR {score} INTO scores;

CLOSE class_b;

PRINT students scores;

QUIT;

Because the purpose of this example is to demonstrate the use of case and spacing, the output is not provided, but can be had in Example 1.10. 因为此示例的目的是演示大小写和间距的使用，所以不提供输出，但可以在示例1.10中使用。

The second section of code is less difficult to read and manage than the first section of code.第二部分代码比第一部分代码更难读取和管理。In the second section of code, vertical spacing separates the one DATA step and two PROC steps. 在代码的第二部分中，垂直间隔分离了一个DATA步骤和两个PROC步骤。Horizontal spacing clearly shows clearly the beginning and ending of the DATA step and PROC steps. 水平间距清楚地清楚地示出了DATA步骤和PROC步骤的开始和结束。 Use of case clearly distinguishes built-in SAS designations from those determined by the user.使用案例可以清楚地区分内置SAS标志和用户确定的标志。

There are clearly multiple methods for documenting and organizing code.显然有多种方法用于注释和组织代码。There is not one right way. 没有一个正确的方法。 However, it is important that the user take into consideration the possibility that code currently being written may need to be reviewed in the future.然而，重要的是用户考虑当前正在编写的代码可能需要在将来被审查的可能性。The more well organized and documented the code, the easier it will be to review the code in the future. 代码越有组织和注释化，就越容易在将来回顾代码。

原文来自：《A SAS/IML Companion for Linear Models》