MATLAB函数文件编写规范
一、函数文件与脚本文件的区别（是什么？）
如果 M 文件的第一个可执行语句以 function 开始，该文件就是函数文件，每一个函数文件都定义一个函数。事实上，MATLAB 提供的函数命令大部分都是由函数文件定义的，这足以说明函数文件的重要性。
从使用的角度来看，函数是一个“黑箱”，把一些数据送进去，经加工处理，把结果送出来。
从形式上看，函数文件区别于脚本文件之处在于：
- 脚本文件的变量为命令工作空间变量，在文件执行完成后保留在命令工作空间中。
- 而函数文件内定义的变量为局部变量，只在函数文件内部起作用，当函数文件执行完后，这些局部变量将被清除。
从结构上来看，脚本文件只比函数文件少了一个“函数声明行”，除此之外，二者的语法及构架等均相同。
二、函数文件的组成部分（怎么写？）
下面将以一个计算平均值的函数为例做出阐述。
在 M 文件编辑器窗口中编写 M 文件并命名为 average.m（文件名与函数名相同）：
function y=average(x)
[a,b]=size(x); %判断输入量的大小
if ~((a==1)|(b==1))|((a==1) & (b==1)) %判断输入是否为向量error('必须输入向量。')
endy=sum(x)/length(x); %计算向量x所有元素的平均值保存 M 文件，函数 average() 接收一个输入参数并返回一个输出参数，该函数的用法与其他 MATLAB 函数一样。在 MATLAB 命令行窗口中运行以下语句，便可求得 1～9 的平均值。
>> x=1:9
x =1 2 3 4 5 6 7 8 9
>> average (x)
ans =5通常函数文件由以下几个基本部分组成：
1、函数定义行
函数定义行由关键字 function 引导，指明这是一个函数文件，并定义函数名、输入参数和输出参数。函数定义行必须为文件的第一个可执行语句，函数名与文件名相同，可以是 MATLAB 中任何合法的字符。
函数文件可以带有多个输入参数和输出参数，例如：
function [x,y,z]=sphere(theta,phi,rho)当然，也可以没有输出参数，例如：
function printresults(x)2、H1 行
H1 行就是帮助文本的第一行，是函数定义行下的第一个注释行，是供 lookfor 查询时使用的。一般来说，为了充分利用 MATLAB 的搜索功能，在编制 M 文件时，应在 H1 行中尽可能多地包含该函数的特征信息。由于在搜索路径上包含 average 的函数很多，因此用 lookfor average 语句可能会查询到多个有关的命令。例如：
>> lookfor average_23、帮助文本
在函数定义行后面，连续的注释行不仅可以起到解释与提示作用，更重要的是为用户自己的函数文件建立在线查询信息，以供 help 命令在线查询时使用。例如：
>> help average_2函数 average_2(x) 用以计算向量元素的平均值。
输入参数 x 为输入向量，输出参数 y 为计算的平均值。非向量输入将导致错误。
4、函数体
函数体包含了全部的用于完成计算及给输出参数赋值等工作的语句，这些语句可以是调用函数、流程控制、交互式输入/输出、计算、赋值、注释和空行。
5、注释
以 % 起始到行尾结束的部分为注释部分，MATLAB 的注释可以放置在程序的任何位置，可以单独占一行，也可以在一个语句之后。例如：
%非向量输入将导致错误
%判断输入量的大小
[m, n]=size(x);总结
典型规范的函数文件的结构总结如下：
- 函数声明行（必写）：位于函数文件的首行，以 MATLAB 关键字 function 开头，定义函数名及函数的输入/输出变量。脚本文件无须函数声明行。
- H1行（必写）：紧随函数声明行之后的以 % 开头的第一注释行。H1 行包括大写的函数文件名和运用关键词简要描述的函数功能。该行将提供 lookfor 命令作为关键词时查询使用。
- 在线帮助文本区（必写）：H1 行及其后的连续以 % 开头的注释行，通常包括函数输入/输出变量的含义调用说明。
- 编写和修改记录：与在线帮助文本区应以一个空行相隔；该行以 % 开头，记录编写及修改 M 文件的所有作者、日期及版本号，以方便后来的使用者查询、修改和使用。
- 函数主体（必写）：规范化的写法应与编写和修改记录以一个空行相隔；这部分内容包括所有实现该 M 函数文件功能的 MATLAB 指令、接收输入变量、进行程序流控制。
说明
- 函数定义名应和文件保存名一致。当两者不一致时，MATLAB 将忽视文件首行的函数定义名，而以文件保存名为准。
- MATLAB 中的函数文件名必须以字母开头，可以是字母、下画线及数字的任意组合，但不可以超过 31 个字符。
- 建议读者在编写 H1 行注释时，尽量采用英文表述方式，这是为了之后在使用过程中关键词检索方便。
三、参考标准案例（供模仿学习）
下面给出一个标准案例供大家参考（本函数文件仅供格式参考）：
function spir len = spirallength(d, n, lcolor)
% CIRCLE plot a circle of radius as r in the provided color and calculate its area
% d：螺旋的旋距；n：螺旋的圈数；lcolor：画图线的颜色；spirlen：螺旋的周长
% spirallength(d,n)：利用蓝色以预设参数的螺旋线
% spirallength(d,n,lcolor)：利用1color颜色以预设参数的螺旋线
% spir_len=spirallength(d,n)：计算螺旋线的周长，并手用蓝色填充螺旋线
% spir_len=spirallength(d,n,lcolor)：计算螺旋我的周长，并用lcolor颜色填充螺旋线% Jia-Hui Su编写于2025.8.24，Jia-Hui Su修改于2025.8.25if nargin > 3error('输入变量过多!');
elseif nargin == 2lcolor = 'b';
end
j = 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), img(spir), lcolor)
elseif nargout == 0plot (spir, lcolor)
elseerror('输出变量过多!');
end
axis ('square')
end