matlab 代码 规范.doc

1. 标识符命名原则标识符的名字应当直观，其长度应当符合“最小长度，最大信息量”原则。1) 非矩阵变量： 变量名应该以小写字母开头的大小写混合形式 譬如：shadowFadingTable，servingSector， rxBufferForRe userID，userPriorityProfile，mcsOneRetrieval等 循环变量应该以i、j、k等为前缀，如for i_File = 1：nFiles for j_Position = 1：nPositions 避免仅用最后的字母s(表示单复数)区别两个变量, 例如point和points. 可以用类似pointArray的形式加以区别。 避免使用一个关键字或者特殊意义的字作为变量名 结构体的命名应该以一个大写字母开头，结构体的命名应该是暗示性的，并且不需要包括字段名（fieldname）应采用Segment.length，避免用Segment.SegmentLength2) 常数： 命名常数（包括全局变量）应该采用大写字母，用下划线分割单词，如MAX_ITERATIONS，COLOR_RED 参数可以以某些通用类型名作为前缀，如COLOR_RED，COLOR_GREEN3） 草稿变量，含矩阵，结构体，元胞： 应用范围比较大的变量应该具有有意义的变量名，作为“草稿变量”的的临时存储空间或者索引可以用短名字。程序员在读到这样的变量的时候，可以假定这个变量的值在没有几行之后的代码中就不会再用到。通常的“草稿变量”整数的时候用i，j，k，m，n（最好少用i，j，因为他们作为MATLAB中的永久性常量表示虚数单位的）。双精度数的时候常用x，y和z。m表示矩阵，没有m表示标量 命名上将cell, struct与MATLAB中最常见的numeric array, 即数值矩阵区分开来. n用于整数变量, 如n_File. m用于一般的矩阵，如matrix_channelHFResponse; c用于cell array, 如cell_temp= cell(1, 4); s用于struct array, 如stuct_user= struct(field, ); matrix，cell，stuct后面的channelHFResponse， user用来表示有特定含义的中间变量，比如matrix_channelHFResponse，用来表示计算channelHFResponse时中间变量。4） 函数： 函数名应该采用小写字母，函数名应该是具有意义的，下划线分割单词如采用： compute_total_width（）避免compwid（） 前缀get/set 应该作为访问对象或者属性的保留前缀，如getobj（.）。 前缀compute应该用在计算某些量的函数的地方computespread（）。 前缀 is应该用在布尔函数的命名的地方，如 iscomplete（）。 Find，initialize类似。2. 编码及文档注释要求及实例2.1 代码版式2.1.1 M文件函数说明function 函数输出参数 = 函数名( 函数输入 )% %此处为函数名，如果不是函数文件就取消此行 % %创建人： %日 期： %修改人： %日 期： %函数变量及功能的简单描述 %-函数主体2.1.2 编码设计本部分说明了M文件编码的设计，包括以下几个方面：垂直间隔，水平间隔，缩进与对齐，注释。2.1.2.1 垂直间隔1、空行空行起着分割块或段落的作用，块（段落）之间一般留一个或两个空行。空行使用规则： 逻辑块之间要留空行； 结构体定义之间要留空行； 函数定义体之间要留空行； 函数体内，完整的控制结构和单独的语句块之间要留空行； 逻辑上密切相关的语句序列之间不要留空行；2、换行注意事项 不在一行使用多个语句。唯一的例外是for语句。For语句的初始化，条件和循环都可以在一行中。例如for (bcnl_num = 0; bcnl_num count) bcnl_num = count; 与case总是独占一行。2.1.2.2 水平间隔 逗号后面要有空格，但是不要在结构的成员与指针操作符前后有空格。例如：foo.index 在 =，&，+，-，, left_border) & (new_shape.x bottom_border) & (new_shape.y ”这类运算符前后都不要留空格。2.1.2.5 缩进与对齐 缩进的水平是一个TAB键，可将编辑器的TAB符定义为4个空格。 嵌套块之间使用4个空格（一个TAB键）的缩进方式。 模块和子程序头以及子程序声明从第一列起。 下列情况下缩进一个水平：n 子程序声明n 条件（看下面）n 循环的结构n switch语句n case labels 条件的else与if有相同的缩进。因此格式就是： fid = fopen（fileName）； if（fid = -1） statements else statements end switch语句的一般格式：switch（condition） case ABC 处理语句； case DEF 处理语句； otherwise 处理语句； end 注释与它们作注释的代码部分有相同的缩进（见Comments）。2.1.2.6 注释1) 程序内部不同功能模块要空一行，同时附注释说明模块的作用、功能。这样程序结构清晰易懂，便于同学间学习交流。例如：% 注释说明下模块一的功能 模块一代码 此处为空行 % 注释说明下模块二的功能 模块二代码2) 多层循环嵌套要在每一个结束的end后加注释说明该层循环结束例:for %循环1for %循环2 for %循环3 代码段 end %循环3结束end %循环2结束end %循环1结束3) 用于理解一小段代码含义的注释，统一写在代码上方，如4）用于理解一句代码的意思可以写在代码后方，但是注意不能超过180字符。太长可以考虑写在代码上方。 5）大段代码，有完整的阶段性的运行结果，需要使用% 形式，使用单元来注释。93. 软件编写说明写作规范作为软件工程过程的一个阶段，程序编码是设计的继续。然而，在编码中所遇到的问题，如程序设计语言的特性和程序设计风格会深刻地影响软件的质量和可维护性。3.1对源程序的质量要求为了保证程序编码的质量，程序员必须深刻理解、熟练地掌握并正确运用程序设计语言的特性。然后，软件工程项目对代码编写的要求绝不仅仅是源程序语法上的正确性，也不只是源程序中没有各种错误，此外，还要求源程序具有良好的结构性和良好的程序设计风格。例如写出的源程序便于阅读，又便于测试和排除所发现的程序故障，就能够有效地在开发期间消除绝大多数在程序中隐藏的故障，使得程序可以做到正常稳定地运行，极大地减小了运行期间软件失效的可能性，大大提高了软件的可靠性。3.2结构化程序设计程序编码这一阶段的工作是把软件的详细设计变换成用某一种程序设计语言编写的可实现的源程序，结构化程序设计就是在编写程序时首先必须考虑的问题。3.2.1结构化程序设计的原则1) 使用语言中的顺序、选择、重复等有限的基本控制结构表示程序逻辑。2) 选用的控制结构只准许有一个入口和一个出口。3) 程序语句组成容易识别的块，每块只有一个入口和一个出口。4) 复杂结构应该用基本控制结构进行组合嵌套来实现。5) 语言中没有的控制结构，可用一段等价的程序段模拟，但要求该程序在整个系统中应前后一致。3.3程序设计风格随着软件规模的增大，复杂性增加，人们逐渐看到，在软件生存期中需要经常阅读程序。特别是在软件测试段和维护段，编写程序的人与参与测试、维护的人都要阅读程序。人们认识到，阅读程序是软件开发和维护过程中的重要组成部分，而且读程序的时间比写程序的时间还要多。因此，程序实际上也是一种供人阅读的文章，所以就有风格问题。程序设计风格包括四个方面：源程序的文档化，数据说明的方法，语句结构和输入/输出方法中值得注意的问题。3.3.1程序的文档化源程序的文档化包括选择标识符（变量和标号）的名字、安排注释以及程序的视觉组织等。1) 符号的命名符号即标识符，包括模块名、变量名、子程序名以及数据区名、缓冲区名等。这些名字应能反应它所代表的实际东西，应有一定的实际意义，使其能够见名知意，有助于对程序功能的理解。2) 程序的注释夹在程序中的注释是程序员与日后的程序读者之间通信的重要手段。正确注释能够帮助读者理解程序，可为后续阶段进行测试和维护，提供明确的指导。大多数程序设计语言允许用自然语言来注释，这就给阅读程序带来了很大的方便。一些正规的程序文本中，注释行数量占到整个源程序的1/3到1/2，甚至更多。注释分为序言性注释和功能性注释。序言性注释通常置于每个程序模块的开头部分，它应当给出程序的整体说明，对于理解程序具有引导作用。有关项目包括：程序标题；有关该模块功能和目的的说明；主要算法；接口说明：包括调用形式，参数描述，子程序清单；有关数据描述（重要的变量及其用途，约束或限制条件，以及其他有关信息）；模块的位置（在那一个源文件中，或隶属于哪一个软件包）；开发简历：模块设计者，复审者，复审日期，修改日期及有关的说明等。（参照软件工程中相应的例子）功能性注释嵌在源程序体中，用以描述其后的语句或程序段是在做什么工作，也就是解释下面要“做什么”，或是执行了下面的语句会怎么样。而不需要解释下面怎么做，因为解释怎么做常常是与程序重复的，并且对阅读者理解程序没有什么帮助。书写功能性注释，要注意以下几点： 用于描述一段程序，而不是每一个语句； 用缩进和空行，使程序与注释容易区别； 注释要正确。3) 视觉组织空格、空行和缩进一个程序如果写得密密麻麻，分不出层次来常常是很难看懂的。优秀的程序员在利用空格、空行和缩进的技巧上显示了他们的经验。恰当的利用空格，可以突出运算的优先性，避免发生运算的错误。3.3.2数据说明虽然在设计阶段已经确定了数据结构的组织及其复杂性。在编写程序时，则需要注意数据说明的风格。为了是程序中数据说明更易于理解和维护，必须注意以下几点：1) 数据说明的次序应当规范化。使数据属性容易查找，也有利于测试，排错和维护。原则上，数据说明的次序与语法无关，其次序是任意的。但出于阅读、理解和维护的需要，最好使其规范化，是说明的次序先后次序固定。推荐，常量说明简单变量类型说明数组说明公用数据块说明所有文件说明。类型说明还可以按照以下顺序：整型变量说明实型变量说明字符变量说明逻辑变量说明。2) 当多个变量名用一个语句说明时，应当对这些变量按字母的顺序排序。3) 如果设计了一个复杂的数据结构，应使用注释说明在程序实现时这个数据结构的特点。例如对C链表结构等都应当在注释中做必要的补充说明。3.3.3语句结构在设计阶段确定了软件的逻辑结构，但构造单个语句则是编码阶段的任务。语句构造力求简单，直接，不能为了片面追求效率而使语句结构复杂化。1) 在一行内只写一条语句，并采取适当的缩进格式，是程序的逻辑和功能变得更加明确。2) 程序编写首先应当考虑清晰性，不要刻意追求技巧性，使程序编写的过于紧凑。软件工程技术要求软件生产工程化、规范化，为了提高程序的可读性，减少出错的可能性，提高测试与维护的效率，要求把程序的清晰性放在首位。因此写出的程序必须让人很容易读懂。3) 除非对效率有特殊的要求，程序编写要做到清晰第一，效率第二。4) 程序编写得要简单清楚，直截了当地说明程序员的用意。5) 首先要保证程序的正确，然后才要求提高速度。6) 尽量使用库函数。7) 避免使用临时变量而使可读性下降。8) 尽量使用公共过程或子程序去代替重复的功能代码段。要注意，这段代码应具有一个独立的功能，不要只因代码形式一样便将其抽出组成一个公共过程或子程序。9) 用调用公共函数去代替重复使用的表达式。10) 使用括号来清晰地表达算术表达式和逻辑表达式的运算顺序。11) 尽量只采用三种基本的控制结构来编写程序。12) 采用逻辑表达式代替分支嵌套。13) 尽量减少使用“否定”条件的条件语句。14) 避免采用过于复杂的条件测试。15) 避免使用空ELSE语句和IFTHENIF的语句。16) 避免过多的循环嵌套和条件嵌套。17) 数据结构要有利于程序的简化。18) 要模块化，使模块功能尽可能单一化，模块间的耦合能够清晰可见。19) 不要修补不好的程序，要重新编写。也不要一味地追求代码的重用，要重新组织。20) 利用信息隐蔽，确保每一模块的独立性。21) 对太大的程序，要分块编写，测试，然后集成。22) 注意计算机浮点运算的特点。23) 不要单独进行浮点数的比较。24) 避免不恰当地追求程序效率，在改进效率前，要作出有关效率的定量估计。25) 确保所有变量在使用前都进行初始化。26) 经常反躬自省：“如果自己不是编码的人，那么能看懂它吗？”3.3.4输入和输出输入输出信息是与用户的使用直接相关的。输入和输出的方式和格式应当尽可能的方便用户的使用。一定要避免因设计不当给用户带来的麻烦。因此，在软件需求分析阶段和设计阶段，就应基本确定输入和输出的风格。系统能否为用户接受，有时就取决于输入和输出的风格。在设计和程序编码时都应考虑下列原则：1) 对所有的输入数据都进行检验，从而识别错误的输入，以保证每个数据的有效性。2) 检查输入项的各种重要组合的合理性，必要时报告输入状态信息。3) 使得输入的步骤和操作尽可能简单，并保持简单的输入格式。4) 输入数据时，应允许使用自由格式输入。5) 应允许缺省值。6) 输入一批数据时，最好使用输入结束标志，而不要由用户指定