科研小技巧——MATLAB的编码风格
引言
MATLAB是我们在科研工作常用的一种语言,虽然最近有说MATLAB开始禁止一部分中国高校对其的使用,将来国产软件也会逐步赶上,但是目前来说,MATLAB还是值得我们进一步学习的。
这一篇文章介绍了MATLAB代码的编写规范,可以帮助我们写出更好的,更可读的代码。
毕竟有这么一句话:Any fool can write code that a computer can understand. Good programmers write code that humans can understand。
任何一个傻子都能写出可以运行的代码,但只有高手才能写出别人能看懂的代码。
拿出你的工匠精神,一起开始学习MATLAB的编码规范吧
1 命名规则
1.1 变量
- 变量名应该采用驼峰命名法,并且以小写字母开头,尽量不要使用下划线分割名词的方式来定义变量
- 大范围使用的变量一定要有有意义的变量名,小范围使用的变量可以用短名称
- 通常短名称里面:i,j,k,m,n代表整数,x,y,z代表小数
- 以n开头的变量,通常用来表示,代表某个对象的数量的变量:nFiles, nSegments
- 变量要么全是单数,或者全是复数,避免用例如point和points代表两个不同的变量
- 表示某个对象编号时,可以采用这两种命名方法:以No为后缀(tableNo, employeeNo),或者以i为前缀(iTable,
iEmployee) 迭代变量应该以i,j,k为名字,或者以i,j,k为前缀,例如:
for iFile = 1:nFiles......
end
- 采用布尔变量时,尽量使bool变量为真时继续执行,例如我们要判断一个文件是否找到,我们应该定义bool变量:isFound,而不是isNotFound。我们只需要判断if isFound,而不是去判断 if ~isNotFound。
- 当变量名称中含有缩写时,仍然要保持首字母小写,其余单词仅首字母大写的规则。例如。html不能写成hTML,isUsa不能写成isUSA
- 要用内置的变量或关键词去给变量命名
1.2 常量
- 常量,以及全局变量应该全部字母大写,并且用下划线分隔单词
- 当要定义一组类似的常量的时候,他们的前缀可以是相同的,例如要定义一组颜色的常量:
COLOR_RED, COLOR_GREEN, COLOR_BLUE
1.3 结构体
- 结构体的名字应以大写字母开头
- 结构体的名字不需要包含在内部的变量名中:例如,要写成
Segment.length
,而不是Segment.segmentLength
1.4 函数
- 函数名要反映其功能
- 函数名应该通通小写,名词中间可以用下划线分隔开
- 函数名一定要清晰,有意义,例如,要写成
computetotalwidth()
,而不是compwid()
- 如果只有一个输出的话,可以以输出量作为函数名字,例如:
mean()
- 没有输出,或者只返回句柄的函数,应该以它具体做什么来命名,例如:
plot()
- 以get/set做前缀,表示用来操作对象或者其属性的函数,例如:
getobj(.); setappdata(.)
- 以compute做前缀,表示用于计算某个变量的函数,表示计算复杂程度很高,例如:
computweightedaverage(); computespread()
- 以find做前缀,表示查找某个元素,某一项的函数,例如:
findoldestrecord(.); findheaviestelement(.);
- 以initialize做前缀,表示构建某个对象的函数,例如:
initializeproblemstate(.);
- 以is做前缀,表示布尔函数,另外还可以采用类似的:has,can,should做前缀。例如:i
soverpriced(.); iscomplete(.) ;hasLicense(.); canEvaluate(.); shouldSort(.);
- 更多类似的前缀:
get/set, add/remove, create/destroy, start/stop, insert/delete,
increment/decrement, old/new, begin/end, first/last, up/down, min/max,
next/previous, old/new, open/close, show/hide, suspend/resume, etc.
1.5 General
- 有时可以考虑在变量名中加入单位,以免引起混淆,例如弧度,incidentAngleRadians
- 除了一些缩写很常见的单词以外,需使用完整单词以避免混淆
- 所有的命名要以英语进行,而不是其他语言
2 文件和组织方式(Files and Organization )
2.1 M文件
- 模块化,尽可能把大的程序抽象为一个个函数,以便于复用
- 让交互更清晰,尽可能避免过长的参数列表,或者过多的全局变量
- 尽可能用已有的函数,不要重复造轮子,不妨在实现一个功能前,多查阅一下文档
- 在不同文件中反复出现的代码,应该包装入一个函数
- 当一个函数仅在一个文件中出现,那么它应该作为子函数,写在同一个文件中
- 为每一个函数都编写一个测试脚本,这是最好的提高代码质量的办法
3 表述(Statements)
3.1 变量和常量
- 为了保证可读性,所有的变量都不应该被复用(不能有两个用途,除非是内存不够)
- 相同类型或相关的变量应该一同声明,不相关的变量则不应该一同声明。例如:
persistent x, y, z; global REVENUE_JANUARY, REVENUE_FEBRUARY
- 在文件开头的注释中说明重要的变量,例如:
% pointArray Points are in rows with coordinates in columns
. - 在常量定义的末尾,通过注释说明其含义,用法或约束,例如:
THRESHOLD = 10; % Maximum noise level found by experiment.
3.1 全局变量和常量
- 相比于全局变量,参数传递更有利于代码的清晰和可维护性。我们可以通过使用persistent或者get***data的方式来避免过多的使用全局变量。
- 减少使用全局常量,如有必要,可以通过将所有全局常量定义在一个m文件中,或者存在.mat文件中
3.2 循环语句
- 循环变量应在循环前就完成初始化,例如:
result = zeros(nEntries,1);
for index = 1:nEntriesresult(index) = foo(index);
end
- 尽量减少使用break和continue,因为这不利于可读性
- 循环的最后一行可以添加注释,用于说明循环到此为止,并且说明循环中执行了哪些任务
3.3 条件语句
- 避免复杂的条件表达式,如有必要,可以引入临时的逻辑变量代替
- 通常情况下会执行的语句存放在if下,而异常情况则存放在else部分
- 一般不用使用 if 0 这样的表达,偶尔用来注释代码倒是也可以接受
- switch语句中,需要包括otherwise这一项
- switch变量最好是字符串
3.4 General
- 不要写密码(看不懂的东西)
- 多写括号
- 表达式中不要出现太多数字,并且某些经常需要进行修改的数字,应该定义为常量
- 避免出现
THRESHOLD = .5
,而应该写成THRESHOLD = 0.5
4 排版,注释和文档(Layout, Comments and Documentation)
4.1 排版
- 缩进有利于展示代码结构
- 内容要保持在前80列里
- 换行的位置要恰当,例如标点符号处,空格处,操作符处,并且新行的开头要与之前的表达式对齐:
totalSum = a + b + c + …d + e;
function (param1, param2,…param3)
setText ([‘Long line split’ …‘into two parts.’]);
- 缩进大约为3个或者4个空格
- 一般来说,一行代码只应包括一行可执行语句
4.2 空格
- 在=,&和|的左右需要插入空格,例如:
simpleSum = firstTerm+secondTerm;
- 在常用的操作符左右最好插入空格,但这是由争议的,例如:
simpleAverage = (firstTerm + secondTerm) / two;
- 逗号后面加空格,例如:
foo(alpha, beta, gamma)
- 代码块中间要用几个空行进行分隔,一般是用三行。也可以使用: %*******************,或者%----------------
4.3 注释
- 经验表明,最好是在编写代码的同时,添加注释,而不是写完以后再加
- 注释要和代码一致,否则会误导读者。而又不能只是复述代码,注释要说明的是how和why,而不是what
- %后面可以跟一个空格,注释的第一个字母可以大写
- 函数头的注释要便于对函数进行查找,以及说明函数用法
- 函数头的注释要说明对输入参数的具体要求,例如:
% ejectionFraction must be between 0 and 1, not a percentage.
% elapsedTimeSeconds must be one dimensional.
- 所有的注释要用英语书写
4.4 文档
- 差的文档也比没有文档要好
- 文档需要包括的内容有,运行的需求,功能,函数接口,测试方法等
- 最好是在写代码之前就先完成文档框架的搭建
- 使用专业的版本控制工具
5 函数头注释规范:
参考博客:如何规范地编写一个MATLAB函数文件
通常,函数文件由函数声明行、H1行、在线帮助文本区、编写和修改记录、函数主体等几个部分组成。格式如下:
function 输出形参表 = 函数名(输入形参表)
在线帮助文本区,其中第一行为H1行
编写和修改记录
函数主体
- H1行是紧随函数声明行之后的以“%”开头的第一注释行。H1行包括大写的函数名和函数功能简要描述,采用lookfor命令可在命令行窗口显示H1行的信息。建议在编写H1注释行时,尽量采用英文表述,这是为了之后的使用过程中关键词检索的方便。
- 在线帮助文本区是包括H1行以及H1行之后的连续的以“%”开头的注释行。通常包括函数输入变量和输出变量的含义以及调用说明。采用help命令可在命令行窗口显示在线帮助文本区的信息。
- 编写和修改记录与在线帮助文本区以一个空行相隔。该行以“%”开头,记录了编写及修改函数文件的作者、日期、版本等内容,以方便后来的使用查询或修改。
- 函数主体应与编写和修改记录以一个空行相隔。这部分内容包括了所有实现该函数文件功能的MATLAB指令。
如下是一个实例:
function spir_len = spirallength(d, n, lcolor) <<< 函数声明行
% SPIRALLENGTH plot a circle of radius as r in the provided color and calculate its area <<< H1行
% 输入参数: <<< 在线帮助文本区
% d: 螺旋的旋距
% n: 螺旋的圈数
% lcolor:画图线的颜色
% 输出参数:
% spir_len:螺旋的周长
% 调用说明:
% spirallength(d,n):以参数d,n画螺旋线,螺旋线默认为蓝色
% spirallength(d,n,lcolor):以参数d,n,lcolor画螺旋线
% spir_len = spirallength(d,n):计算螺旋线的周长,并以蓝色填充螺旋线
% spir_len = spirallength(d,n,lcolor):计算螺旋线的周长,并以lcolor颜色填充螺旋线 <<< 在线帮助文本区% 版本号V1.0,编写于1999年9月9号,修改于1999年9月10号,作者:亚索 <<< 编写与修改记录if nargin > 3 <<< 函数主体error('输入变量过多!');
elseif nargin == 2lcolor = 'b'; % 默认情况下为蓝色
endj = sqrt(-1);
phi = 0 : pi/1000 : n*2*pi;
amp = 0 : d/2000 : n*d;
spir = amp .* exp(j*phi); if nargout == 1spir_len = sum(abs(diff(spir))); fill(real(spir), imag(spir), lcolor);
elseif nargout == 0plot(spir, lcolor);
elseerror('输出变量过多!');
endaxis('square');
参考文献
Richard Johnson. MATLAB Programming Style Guidelines. 2002
科研小技巧——MATLAB的编码风格相关推荐
- MATLAB中的一些小技巧 - [MATLAB]
http://liuxqsmile.blogbus.com/logs/17451138.html MATLAB中的一些小技巧 1. Ctrl+C 中断正在执行的操作 如果程序不小心进入死循环,或者计算 ...
- 『科研小技巧』如何做一篇文献阅读汇报? 细节 | 思路 | 方法
一.阅读: 1.摘要: 1)最精华的部分 2)着重理解关键词句 2.前言 1)用"摘要"中的关键词法解析前言 2)寻找连词, ...
- 科研小技巧——制作学术会议报告视频的完整流程
引言 近期由于受到疫情的影响,许多学术会议都转到线上举行了.由于各个地方时区不同,许多参会者有可能没办法在自己作报告的时间按时进入线上会议,所以许多会议都要求提供学术报告的视频版本,这篇文章就会介绍, ...
- 科研小技巧 | 用ArcGIS绘制研究区地图
目录 01 地图的导入 02 设置十段线小图框 03 设置研究区示意图 04 添加细节04添加细节 05 添加省份名称 06 对研究区额外上色 论文用图对准确性和美观度有一定要求,而ArcGIS具有强 ...
- PHP小技巧之UNICODE编码转中文汉字
PHP的方式为: function decodeUnicode($str) {return preg_replace_callback('/\\\\u([0-9a-f]{4})/i',create_f ...
- 【科研小技巧】Word(2016)绘制三线表样式
问题描述: 写论文时经常需要用到绘制三线表,而每次都先画好表格后慢慢修改,很是麻烦,所以这里介绍一种制作表格样式的方式,以后使用三线表时只需选择样式就OK了 1. 首先,随便绘制一个表格,像下面这样 ...
- react 代码编写原则_如何编写易读的React代码— 10种编码风格技巧
react 代码编写原则 by Nirmalya Ghosh 由Nirmalya Ghosh 如何编写易读的React代码- 10种编码风格技巧 (How to write highly readab ...
- matlab 取点画图,matlab绘图小技巧-图像光滑数据取点
原标题:matlab绘图小技巧-图像光滑&数据取点 小助理之前介绍过Matlab,,一款计算机.医学与生物学的软件,今天转载一篇实操,简单易上手~ 用cftool插值绘图得到拟合后的图像,然后 ...
- 面试技巧篇 -- 编码风格 (Coding Style)
面试技巧篇 – 编码风格 (Coding Style) Coding Style 在面试中有什么影响? 算法面试已经是绝大多数high-tech公司的敲门砖,这也导致了求职者花费大量时间准备算法刷题, ...
最新文章
- 在ubuntu 14.04 64bit下配置安装PyQt4(python2.7和python3.4)
- 在.Net Micro Framework中显示汉字
- 集合中元素的数据类型可以不同,但集合中不能嵌套列表、元组、集合、字典
- 使用Slf4j查看日志输出
- linux集成开发环境
- 关于遍历字典的二三事
- Atitit.ALT+TAB没反应车and 点击任务栏程序闪烁但是不能切换
- 工业和能源1994-2019年省级面板数据
- 现代信号处理 张贤达_信号处理领域著名科学家、清华大学张贤达教授逝世,享年 74岁...
- RabbitMQ(一)
- Action Recognition——Deep Domain Adaptation in Action Space——BMVC2018
- AI魔幻行为大赏:细数机器视觉的9大应用场景
- sspanel php,sspanelv3魔改版邮件设置指南及常用配置
- 医学用计算机吗,学临床医学必须要用笔记本电脑吗?
- android 模拟自动点击,自动点击模拟器app
- 红牛分公司数据part02
- 表格对角线两边打字_表格斜线一分为二怎么打字(excel斜杠分割表格打字)
- js处理blur事件触发多次
- linux fcitx改mac输入法,Linux安装fcitx输入法
- linux系统基础知识总结
热门文章
- 302-驻留集管理,清除策略和加载控制
- 网络直播被严查,机器如何帮助鉴别小黄图?
- CENC InterTrust DRM 及 player中的应用原理
- 【无标题】ssh登陆 提示 session ended very soon
- July, 15(R)
- halcon 图像差分_Halcon学习(10)边缘检测(一)
- Ubuntu永久修改IP
- mysql百万数据 查总数都特别慢_mysql百万级数据分页查询缓慢优化方法
- 程序员为什么都容易“喜当爹”
- 计算机科学与技术国家重点一级学科,最新国家重点一级学科一览