Code Formatting(代码格式)

From wiki.visual-prolog.com

Revision as of 12:47, 17 June 2015 by Yiding (talk | contribs) (Created page with "(以下内容,译自Category:Tutorials中的Code Formatting。更多内容可以参看Category:Chinese。) <P>本文描述用于Visual Prolog程序的编码标准...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

(以下内容,译自Category:Tutorials中的Code Formatting。更多内容可以参看Category:Chinese。)

本文描述用于Visual Prolog程序的编码标准,Visual Prolog系统自身也是这样写的。用户文档中的例子也是使用这个标准。因此,PDC也推荐用户使用这个标准。

关键字

关键字使用小写字母。在文档中关键字用粗体无衬线字体,如Arial。缺省颜色为暗绿色。

constants
domains
facts
predicates
class
interface
...

半关键字

Visual Prolog中对各种语法结构使用了许多记号。这些词也都是使用小写(除了用C语言写的C调用中的惯例外)的普通无衬线字体,其颜色根据它们不同的性质分成两种:如果是表示一种选择则用海军蓝色,如果是结构词则使用暗绿色。

erroneous
failure
procedure
determ
nondeterm
multi
language
as
stdcall
c
...

下面的例子示出颜色与字体的使用:

predicates
    myPredicate : (string Value) procedure (i) language stdcall as "_myP"

文字

文字的颜色为蓝色。

1
"Hello world!"

标识符

标识符的一般格式可以用下面的EBNF文法描述:

<Identifier> = <Prefix> <WordGroups> <Suffix>
<WordGroups> = <WordGroup> { ‘_’ <WordGroup> }*
<WordGroup> = <Word>+

前缀与后缀用于表示标识符的种类,并连同每一类标识符一道处理。除了对那些整个标识符的首字母必须小写的情况而外,单词要大写。

变量都以大写字母打头,所有其它的都是小写打头。

文档中除了关键字都使用衬线字体,如Times New Roman。

常量

常量没有前缀和后缀,由小写字母开头。

numberOfRows
pi
logErrorMsg

变量

变量没有前缀或后缀。如前述(也是Prolog的要求),变量以大写字母开头,文档中变量用绿色。

X
File
OutputStream

谓词

谓词没有前缀。不过,“try”可用来标示谓词是确定的,尤其是用来区分一个谓词的确定版本和与其相应的过程版本。后者会产生异常来代替失败。如:

trySetValue : (integer Value) determ (i).
setValue : (integer Value) procedure (i).

以isXxxx及hasXxxx的形式作为测试谓词是个好方法(当然名称也要对得上号)。

谓词没有后缀,除非需要用它来避免混淆,并推荐使用以下的后缀:

  • _fact nondeterm fact
  • _nd nondeterm/multi
  • _err erroneous
  • _fail failure
  • _dt determ
  • _multi multi 注意,一般multi 谓词使用_nd做后缀,但如果情况需要也可以用_multi
setWindowFont
member
member_nd
ganttBar_fact

域没有前缀。_list用于不具有(事关)域名的表(list)域的后缀,例如,一个数据库的记录是数值表,则记录的域名以数值表为好,就可以用这样的后缀。注意域名以小写字母开头。同样的方法适用于串、整数等域的类似情况。

string
value
record
record_list

类与接口

类与接口没有前辍。

string
inputFile
template
inputStream

COM接口传统上是以"I"开头的,这个"I"保留下来了,但要改为小写:

iUnknown
iDispatch

格式

本节细述程序代码的格式。格式是指断行,缩排,列排(列对齐)等。缩排是指在一行的起始留出若干空格;而列对齐涉及的是非行首构件的排列问题。

断行

断行应遵循以下规则:

  • 外层的结构总在内层结构前断行。
  • 不同谓词的子句间至少用一空行加以分隔。
  • 同一谓词的子句间不要用空行分开。
  • 段关键字前至少留出一行空行。
  • 谓词调用不是嵌套时,自己独占一行。
  • 截断(不管它看起来多微小)占一行。
  • 子句头部独占一行。

缩排

缩排是指行首留出若干空格,它有以下规则:

  • 缩排的宽窄量要一致(比如都占4个空格)。
  • 如果圆括号中的一组内容必须要分成若干行,则应在左括号后立即断行,之后的缩进应该增加一步,而不要与上面的左括号对齐。

列对齐

不使用列对齐(列对齐是指使各个不在行首的结构排列对齐,在行首的构件的对齐使用缩排的规则)。

空格符

  • 逗号后加空格。
  • 在函子(包括表)内,逗号后的空格可以略去。
  • 谓词、事实、常数的声明中,在“:”前后加空格。
  • 圆括号前后不要有空格,除非圆括号与诸如“ :- ”,“ : ”这样的通常前后有空格的记号相邻。

结构

这节逐项讨论结构。

段关键字独占一行。段关键字缩进,该段内的构件缩进一步。段间至少用一个空行来分隔。

clauses 
    p.
 
clauses
    q.

类、接口、实现等

类的起始与结束各自独占一行。类的结束行总是包含有类的标识名,类中的段关键字不要缩进。

class specialOutputFile : outputFile
predicates
    ...
end class specialOutputFile

其它的(接口、实现等)与此相同。

谓词声明

谓词声明含有参数名,这些名字使用变量的格式。procedure模式的声明可以省略。

predicates
    increment : (integer X) -> integer Y.
    bubbleSort : (integer_list Input) -> integer_list SortedList.
    myPredicate_nd : (
            aVeryLongDomainName StrangeFirstParamanter, 
            anotherLongDomainName PlainSecondParameter)
        nondeterm (i,o)
        determ (i,i).

注意左括号之后的断行及其后增加了的缩进。

函子总要为其参数命名;这些名字使用变量的格式。如果一个域声明分为若干行,不管所有函子在一行还是分为若干行,也不管函子的参数都在一行还是分占若干行,都应在等号后做第一次断行。

domains
    value =
        int(integer Value);
        real(real Value);
        str(string Value).
 
domains
    aVeryLongDomainName =
        x(integer X); y(integer Y).
 
domains
    anotherLongDomainName =
        aFunctorWithManyArguments(
            integer X,
            integer Y,
            integer Z,
            integer RedColourComponent,
            integer BlueColourComponent,
            integer GreenColourComponent).

子句

子句的头部独占一行。子句体中各调用独占一行。如果一个子句的头部必须断行,则其参数应比头部多缩进两步,因为不这样它的缩进位置就会与子句体一样。

clauses
    myPredicate(X, Y) :-
        callNoOne(X, Y, Z),
        !,
        callNoTwo(Z, Y).
    myPredicate(X, Y) :-
        callNoThree(X, Y).
 
clauses
    aPredicateWithManyArguments(FirstArgument, SecondArgument,
            X, Y, Z, ErrorNo, ErrorMsg) :-
        callNoOne(FirstArgument, SecondArgument, X, Y, Z,
            ErrorNo, ErrorMsg),
        callNoTwo(),

Non-deterministitic Loops

对非确定调用结果的循环是Prolog中常用的一种结构。对这种结构建议把循环体加深缩进:

clauses
    myPredicate() :-
        member(X, [1,2,3,4,5,6]),
            doAction(X), % extra indentation in the "loop body"
        fail.
    myPredicate().

可能的话,尽量使用 foreach 结构。

Microsoft Word中的代码格式化

本节给出一些在Microsoft Word中便于格式化代码的提示。

可以构造一个名为 code 的段落格式,再构造一些字符格式:keyword, parameter, var, literal, 等。

code 的段落格式可以用如下的属性:

  • 基于正文段落格式,它可以为下面的代码段提供合适的空间。
  • 关闭拼写检查等。
  • 缩进一个量,并将缺省的tab设为与这个量一致。这个量可以用0.63cm,因为这也是其它段落格式的缺省值。
  • 设置孤行控制等内容,避免程序不必要地跨页。keyword 字符样式把字体改为Arial,粗体,暗绿色;var 把颜色改为绿色,literal 把颜色改为蓝色。

输入代码时,先选择code段落格式。输入中使用软回车(shift+newline),用tab键缩进。

节省时间:可以用格式刷来搞定各种关键字的格式问题。

References