Matlab 编程风格指南

1. 简介
2. 命名规则
- 2.1. 变量
- 2.2. 常数
- 2.3. 结构体
- 2.4. 函数
- 2.5. 摘要(General)
3. 文件和结构
- 3.1. M文件
- 3.2. 输入输出
4. 基本语句(Statement)
- 1. 变量与常数
- 2. 循环语句
- 3. 条件语句
- 4. 小结
5. 布局,注释与文档
- 5.1. 排版(Layout)
- 5.2. 空白空格
- 5.3. 注释
- 5.4. 文档

1. 简介

本指南主要考虑的是代码（格式）的正确性、清晰性与通用性。本指南的
目的在于帮助写出更可能正确、易于理解、更具有共享性与更利于维护的代码

2. 命名规则

A rose bu any other name confused the issue.

2.1. 变量

变量的名字应该能够反映他的意义或者用途

变量名应该以小写字母开头的大小写混合的形式譬如：linearity ，credibleThreat，qualityofLife 等

分割复合变量名的各个部分中间通常有两种做法，前面例子的这种（以大写字母分割）是其中的一种，虽然可读性比较好，但是在其他语言变量名中并不很常用。另外一种考虑的方法是在变量名中采用下划线

应用范围比较大的变量应该具有有意义的变量名，小范围应用的变量应该用短的变量名
实际上大多数变量都应该具有有意义的变量名

注意草稿变量可以比较简单，用k,m,n,尽量不要使用i,j跟虚数歧义，但还是不要用k,m,n了吧

前缀n应该用于作为数值对象申明的时候，是一种很好的习惯如nFiles，nSegments

实际上和python中我们的使用是一样的，复数和单数应该区分开来，但是在python中我们常是直接加s，在matlab中我们可以利用后缀Array，例：point， pointArray （前者为单数，后者为复数）

只代表单个实体数据的变量可以加以后缀 No 或者是前缀 i

符号 No 来自于数学在表明实体数据的时候的建立规则。例如tableNo，empolyeeNo
前缀 i 使得变量命令可以循环进行。例如变量名：iTable，iEmployee

循环变量应该以 i、j、k 等为前缀
for iFile = 1：nFiles
…
end

for iFile = 1：nFiles
for jPosition = 1：nPositions
…
end
end

否定式的布尔变量命名是应该避免的
当采用否定式的布尔变量命名法时，如果采用逻辑运算取非的操作符号对变量进行
链接运算的时候，将出现双重否定的情况。例如，用～isNotFound 没有采用 isFound 直观。
因此避免使用类似于 isNotFound 这样的变量名

缩写形式，即使是通常的大写缩写，也应该于小写字母混合使用

全部使用大写字母作为基本的变量名与上面给出的命名规则相冲突。很显然这将使得其不具有可读性。当这样的变量名与其他的相联合的时候，其可读性严重降低；
采用： html，isUsaSpecific，checkTiffFromat（）
避免使用：hTML，isUSASpecific，checkTIFFFormat（）

2.2. 常数

命名常数（包括全局变量）应该采用大写字母，用下划线分割单词
示例： MAX_ITERATIONS，COLOR_RED
参数可以以某些通用类型名作为前缀
这样命名的常数给出了个附加信息，指明它们属于哪类以及他们代表的意义。如：COLOR_RED，COLOR_GREEN，COLOR_BLUE

2.3. 结构体

结构体的命名应该以一个大写字母开头
有助于区分结构体与普通变量
结构体的命名应该是暗示性的（implicit），并且不需要包括字段名（fieldname）
应采用 Segment.length避免用 Segment.SegmentLength

2.4. 函数

函数名应该能够说明函数的用途

函数名应该采用小写字母，当然我们也可使用下划线来增加可读性，我就经常这样用

函数名应该是有意义的，可以短，可以是缩写，但是在最初出现的地方一定要标注出来完整的单词

单输出变量的函数可以根据其输出参数来命名，像mean()

没有输出变量或者返回值作为句柄的函数应该根据其实现的具体功能来命名
这种规则可以增强可读性,使得很清楚函数应该(或者不应该)干什么。这就使得代码很简洁明了并且易于理解其功能，像plot()

2.5. 摘要(General)

所有的命名都应该以英文形式给出
英语是国际研发交流的时候最适合的语言

3. 文件和结构

将代码结构化，不只是在文件内部，还包括在文件之间，有思想的程序结构块分隔和条理化可以增加代码的质量

3.1. M文件

模块化
编写一个大程序的最好的方法是将它以好的设计分化为小块（通常采用函数的方式）。
这种方式通过减少为了理解代码的作用而必须阅读的代码数量使得程序的可读性、易于理
解性和可测试性得到了增强。超过编辑器两屏幕的代码都应该考虑进行分割。并且设计规划很好的函数也使得它在其他的应用中可用性增强了
确保交互过程清晰
函数通过输入输出参数以及全局变量与其他代码交互通信。使用参数几乎总是比使用
全局变量清楚明了。采用结构化设计可以避免那种一长串儿的输入输出参数的形式
分割
所有的子函数和所有的函数都应该只把一件事做好，每一个函数都应该隐藏一些东西
利用现有的函数
开发一个有正确功能的，可读的，合理灵活的哈桑农户是一项重大意义的任务。或许寻找一个现成的提供了要求的部分，甚至全部功能的函数应该更快更具正确性
改变是不可避免的，任何在多个m文件中出现的代码块都应该考虑用函数的形式封装起来

子函数
只被另外一个函数调用的函数应该作为一个子函数写在同一个文件夹中，代码会更容易理解和维护

3.2. 输入输出

编写输入/输出模块
输出要求可以无需特别注意就可以根据变化而改变，输入的格式与内容根据变化的时候经常很混乱。找到处理输出的地方进行改善，提高其可维护性。避免将输入/输出部分的代码与计算功能的代码混淆在一起，单个函数的预处理的时候除外。各种功能混合的函数的可再用性一遍很小

格式化输出使得其易于利用
如果输出很大可能是人工阅读，那么就让输出采用易于越多的描述性的方式。如果输出更多的可能是通过其他软件调用而不是人，那么应该使得输出易于解析。
如果这以上两种情况都很重要，将输出表达成易于解析的格式，并编写一个格式化输出的函数用来产生一个人工可读的输出版本

4. 基本语句(Statement)

1. 变量与常数

变量不应该重复使用(不应赋予为不同的定义)

同种类型的相近的变量可以在同一个语句中定义
不相近的变量应该不要在同一个语句中定义
通过变量分组可以增强其可读性。
示例： persistent x，y，z
global REVENUE_JANUARY，REVENUE_FEBRUARY

注意在文件开始部分的注释中为重要变量编写文档
在其他的编程语言中，在变量申明的地方为他们编写文档是一种标准话的操作。既然
MATLAB 不需要变量申明，这种信息就可以在注释中提供。
示例：％ pointArray Points are in rows with coordinates in columns

注意在语句行注释的最后为常数编写文档
这对参数有关合理性、应用和约束等附加信息。
示例： THRESHOLD = 10；％Maximum noise level found by experiment。

全局变量
我们应该尽可能少使用全局变量，参数传递在代码清晰性和可维护性方面都比用全局变量要好

2. 循环语句

循环变量应该在循环开始前立即被赋值
这可以提高循环的速度，有助于防止循环没有执行所有的可能索引而产生的虚假值。
示例：
refult = zeros( nEntries，1)；
for index = 1：nEntries
result（index）= foo（index）；
end

在循环中应该尽量少用 break 与 continue
这些结构可以与 goto 相比较，只有当他们可以证明用这些结构可以比他们相应的结
构化部分有更好的可读性的时候，才可以使用

在嵌套式循环的时候应该在 end 行加上注释
在长的嵌套循环的 end 命令行添加注释可以有助于弄明白哪些语句在那个循环体内、
在此处之前已经完成了哪些功能

3. 条件语句

应该避免复杂的条件表示式，而采用临时逻辑变量进行替代
通过对表达式指定逻辑变量，使得程序更能够自为文档，使得程序结构更易于阅读与调试。
示例：
避免使用：
if（value>=lowerLimit）& (values<=upperLimit) &~ismember(value,valueArray)
……
……
end
而应该用如下的方式代替：
isValid = （value=lowerLimit）& (values<=upperLimit)；
isNew = ~ismember(value,valueArray)
if ( isValid & isNew)
……
……
end

在 if else 结构的时候，发生较频繁的事件应该放在 if 部分，例外情况放在 else 部分
这样通过将例外情况排除在常规执行路径之外可以提高程序的可读性

一个 switch 语句应该包含 otherwise 条件
将 otherwise 情况遗漏在外是一种通常错误，这或许会导致不可预测结果。
正确示例：
switch（condition）
case ABC
处理语句；
case DEF
处理语句；
otherwise
处理语句；
end

4. 小结

避免含糊代码
或许是因为莎士比亚的这句“简单是智慧的灵魂”所感染，在一些程序员之中存在这样一种倾向：将 MATLAB 代码写得很简洁，甚至朦朦胧胧。编写简练的程序是一种表现语言的特色的方式。然而，在很多情况下，清楚是核心问题。正如 TMW 的 Steve Lord 写
道：“从现在开始，一个月后，如果我再看这些代码，我能否理解他们是干什么的？”
尽量避免出现 Cool Hand Luke 中上尉所描述的那样：“现在我们到了一个无法交流的地方。”
这个论点在很多作者的著作中都重点强调的。Martin Fowler 写道：“ 任何一个傻子都
可以写出一个计算机能够理解的代码。好的程序员写出人能够理解的代码。”Kreitzberg与 Shneiderman 写道：“编程可以很有趣，密码学同样也可以很有趣，但是，他们不可以混合在一起。

采用附加说明
MATLAB 对于操作运算有个优先级的文档，但是谁愿意记住它们的具体内容呢？如
果在某些地方有任何疑问，采用附加说明使得表达清楚。特别是在扩展的逻辑表达式的时
候尤其有用。

尽量在表达式中少用数字。可能会改变的数字应该用常数代替
如果一个数字它的本身没有明确的意义，采用将它命名为常数可以加强程序的可读
性。并且，改变参数的定义比改变文件中所有的相应出现地方的数字要容易得多

浮点常数应该在小数点前面写上一个阿拉伯数据
这是坚持数学习惯的语法要求，而且，0.5 比 .5 更具有可读性，因为 .5 很有可能被误认为是整数 5。
采用 THRESHOLD = 0.5；
避免使用 THRESHOLD = .5；

5. 布局,注释与文档

5.1. 排版(Layout)

排版
排版的目的是帮助读者理解代码，缩排特别有助于展示程序的机构。
应该将代码内容控制在前 80 列之内
对于一个编辑器、终端仿真器、打印机、调试器以及文件的通常列数是 80 列，因此
通常几个人的程序共享的时候，大家通常将内容控制在前 80 列之内。在程序员之间传递
文件的时候，避免无意识的分行可以增强程序代码的可读性。
在恰当的地方应该将行进行切分
当语句长度超过 80 列的限制的时候应该切分行。通常：
● 在一个逗号或者空格之后进行断开；
● 在一个操作符之后断开；
● 在表达式开始前的地方重新开始新的一行
示例：
totalSum = a +b +c +…
d+e；
function (param1，param2，…
param3)
setText（[‘Long line split’…
‘into two parts.’]）；

基本缩排应该是 3 或者 4 个空格
好的缩排或许是唯一的一个展现程序结构的好方法。
1 个空格是缩排太小而不能够强调出代码的逻辑分层；2 个空格的缩排在为了减少因为嵌套循环超过 80 列而切分行的断裂的时候被建议采用，而 MATLAB 通常没有太多太深的循环嵌套。大于 4 个空格的缩排使得因为行切分的机会增大而使得代码的可读性变差。4 个空格的缩排是 MATLAB 编辑器的缺省设置，在以前的一些版本，缺省缩排是 3个空格

应该与 MATLAB 编辑器的缩排一致
MATLAB 编辑器提供了使得代码结构清晰的缩排，并且与 C++与 Java 推荐使用的缩
排方式相一致。
通常情况下，一行代码应该只包含一个可执行语句
这种方式可以提高可读性，并且允许 JIT 加速。

短的单个 if，for 或者 while 语句可以写在一行
这种方式更加紧凑，但是她失去了缩排格式提示的优点。
示例：
if（condition），statement；end
while（condition），statement；end
for iTest = 1：nTest，statement；end

5.2. 空白空格

空白空格通过将各个单独组成部分的语句独立出来而增强了程序的可读性

在 =，&，与 | 前后加上空格
在指定的字符前后加上空格可以增强其可视化的分割提示，明显地将语句左右两部分分开。在二值逻辑操作符前后加上空格可以使得复杂的表达式清晰。
示例：
simpleSum = firstTerm+secondTerm；

常规的操作符两边可以加上空格
这种方式是有争议的。部分人认为它可以增强其可读性。
示例：
simpleAverage = (firstTerm + secondTerm) / two；
1 : nIterations

逗号后面可以加上空格
这些空格可以增强可读性。有些程序员为了避免切分行而不采用这种方式。
示例： foo(alpha, beta, gamma)，也可以 foo(alpha,beta,gama)

分号或者同一行多条指令的逗号之后应该加上一个空格字符
空格加强可读性。
示例：if （pi>1），disp( ‘Yes’ ), end

关键字后面应该加上空格
这种方式有助于区分关键字与函数

一个块（block）内部的一个逻辑组语句应该通过一个空白行将其分隔开
在块的逻辑单元之间加入空白行可以增强代码的可读性

块（blocks）之间应该用多行空白行分隔
一种方式是采用 3 隔空白行。采用大的间隔来与块内分隔相区别，使得在文件中，
块看起来非常明显。另外一种方式是采用注释符号后面跟多个诸如*或者－。

通过排列成行列整齐的方式来加强可读性
代码排列成行列整齐的形式可以使得切分表达式容易阅读与理解。这种排版也有助于
揭示错误。
示例： weithedPopulation = (doctorWeight * nDoctors) + …
(layerWeight * nLawyers) + …
(chiefWeight * nChiefs)；

5.3. 注释

注释的目的是为代码增加信息。注释的典型应用是解释用法、提供参考信息、证明结果、阐述需要的改进等。经验表明，在写代码的同时就加上注释比后来再补充注释要好

注释不能够改变写得很糟糕的代码效果
注释不能够弥补因为代码命名不当、没有清晰的逻辑结构等造成的缺陷。存在这样缺
陷的代码应该重写。Steve MaConnell 说道：“提高代码质量，然后再增加文档以进一步使
得其清晰。

注释文字应该简洁易读
一个糟糕的或者是无用的注释反而会影响读者的正常理解。N.Schryer 提到：“如果代码与注释不一致，那么或许两者都是错误的。”一个通常更重要的是注释应该讲的是“为什么”（Why）和“怎么做”（how），而不是“是什么”（what）。

函数头部的注释应该支持利用 help 与 lookfor 查询
help 命令打印出文件开题的第一块注释行。lookfor 命令搜寻路径上的所有 m 文件的
第一个注释行，尽量在这一行中包含可能的搜索关键字。

函数头部的注释应该讨论对输入参数的特殊要求等
使用者通常需要知道输入是否有特殊的单位要求或者矩阵类型要求
示例： % ejectionFraction must be between 0 and 1, not a percentage.
% elepsedTimeSceconds must be one dimensional

函数头的注释应该描述其任何副作用（side effects）
副作用是指函数的行为而不是指输出参数的指定。一个常见的例子是图的产生，在头说明中描述其副作用以便他们可以在用 help 指令的打印输出的时候是可见的。

通常情况下，函数头注释的最后一句应该是重申函数语句行
这可以让用户在一眼扫过 help指令的打印输出时可以发现函数的输入输出参数用法。

在函数头注释中讲函数名用大写的形式表达是一个有争议性的规则
在 MathWorks 的开发中采用的是这样的规则，这样可以突出函数名。很多其他作者
不遵循这条规则，因为其缺点是通常在代码中函数名是小写字母。

避免在函数头说明的 help 打印输出中的混乱
在函数文件开头的附近通常包括版权以及修改日期等信息。在文件头说明和这些信息
说明之间应该加入一个空白行，以避免在用 help 指令的时候显示出来。

所有的注释语句应该用英语写作
在国际环境中，英语是最提倡使用的语言。

5.4. 文档

文档规范化
作为有用的文档应该包含一个对如下内容的可读性的描述：代码打算干什么（要求），它是如何工作的（设计），它依赖于什其他什么函数以及怎么被其他代码调用（接口），以及它是如何测试的等。对于额外的考虑，文档可以包含解决方案的选择性的讨论以及扩展与维护的建议

首先考虑书写文档
一些程序员相信的方法是：“代码第一，回答问题是以后的事情。”而通过经验，我们绝大多数人知道先开发设计然后再实现可以导致更加满意的结果。如果将测试与文档留在最后，那么开发项目几乎不能够按期完成的。首先书写文档可以确保其按时完成甚至可能减少开发时间。

修改
一个专业的对代码修改进行管理和写文档的方法是采用源程序控制工具。对于很简单
的工程，在函数文件的注释中加入修改历史比什么都不做要好

Matlab编程风格指南--Richard Johnson(命名规则,文件与结构,基本语句,布局,注释与文档)相关推荐

MATLAB 编程风格指南
MATLAB 编程风格指南 --Richard Johnson Version 1.5,Oct. 2002 版权: Datatool 所有翻译:Genial @ USTC &qu ...
Google C++编程风格指南阅读笔记之命名、注释和格式
文章目录前言命名约定类型命名变量命名枚举命名宏的命名注释注释风格文件注释类注释函数注释变量注释类的数据成员全局变量实现注释 TODO注释格式行长度空格还是制表符函 ...
Google C++编程风格指南
[译]Google C++编程风格指南(八)[完] 2008年09月03日星期三 17:06 原文地址:Google C++ Style Guide 规则之例外前面说明的编码习惯基本是强制性的,但 ...
谷歌 Java 编程风格指南
点击上方蓝色"程序猿DD",选择"设为星标" 回复"资源"获取独家整理的学习资料! 来源 | http://hawstein.com/201 ...
深度解析Google Java 编程风格指南
这份文档是Google Java编程风格规范的完整定义.当且仅当一个Java源文件符合此文档中的规则, 我们才认为它符合Google的Java编程风格. 与其它的编程风格指南一样,这里所讨论的不仅仅是 ...
Google Java编程风格指南中文版
作者:Hawstein 出处:http://hawstein.com/posts/google-java-style.html 声明:本文采用以下协议进行授权: 自由转载-非商用-非衍生-保持署名|C ...
Google Java编程风格指南中文版(转)
作者:Hawstein 出处:http://hawstein.com/posts/google-java-style.html 声明:本文采用以下协议进行授权: 自由转载-非商用-非衍生-保持署名|C ...
Google Java编程风格指南（献给那些没有良好编码习惯的程序员们）
作者:Hawstein 出处:http://hawstein.com/posts/google-java-style.html 声明:本文采用以下协议进行授权: 自由转载-非商用-非衍生-保持署名|C ...
Google Java编程风格指南
Hawstein's Blog Home Archive Categories Sitemap About Su 前言源文件基础源文件结构格式命名约定编程实践 Javadoc 后记前言这 ...
Qt——自定义编程风格指南（未完成）
文章目录前言一.头文件模板规则 1. 尽量所有"#include"放在.h文件头部 2. "#include"包含的类顺序 3. 头文件中变量.函数属性 ...

Matlab编程风格指南--Richard Johnson(命名规则,文件与结构,基本语句,布局,注释与文档)