自定义函数入门：function y = my_func(x) 的输入输出参数写法

1. 为什么函数签名值得单独讨论

大多数编程入门教程把函数定义当作一个"五分钟就能学会"的知识点：写个function关键字，括号里放输入，等号后面放输出，完事。但如果你真正在工程项目里维护过几百个函数的代码库，就会知道函数签名远不止是语法问题。它是模块之间最核心的接口契约，决定了调用者需要提供什么、被调用者承诺返回什么、以及当约定被违反时系统如何响应。

MATLAB作为科学计算领域使用最广泛的语言之一，其函数定义机制经历了从简单到复杂的演进。早期MATLAB（1990年代）的函数定义非常朴素，没有参数验证，没有类型声明，甚至没有默认值机制。开发者只能靠文档和约定来保证调用正确性。到了R2019b版本，MathWorks引入了arguments验证块，这标志着MATLAB函数签名设计进入了一个新阶段。

本文评述：函数签名的演进方向，本质上是从"约定式契约"走向"声明式契约"。约定式契约依赖开发者的自觉和文档，而声明式契约把约束编码进语言本身，让编译器/解释器替你检查。这个趋势在Python（类型注解）、TypeScript（类型系统）、Rust（所有权签名）中都能观察到，MATLAB的arguments块也是同一逻辑的体现。

笔者认为，理解函数签名有三个层次：第一层是语法层，知道怎么写不报错；第二层是语义层，理解参数如何传递、作用域如何工作、返回值如何绑定；第三层是设计层，能够根据工程需求选择合适的签名模式。大多数教程停留在第一层，少数涉及第二层，而真正决定代码质量的是第三层。

2. MATLAB函数定义的基本语法结构

2.1 最小可用函数

一个MATLAB函数的最小形式包含四个要素：function关键字、输出参数列表、函数名、输入参数列表。以标题中的例子为例：

function y = my_func(x)
    % MY_FUNC 对输入执行某种计算
    % 输入: x - 数值标量或数组
    % 输出: y - 与x同尺寸的结果
    y = x.^2 + 1;
end

这段代码定义了一个名为my_func的函数，接受一个输入参数x，返回一个输出y。文件必须保存为my_func.m，文件名与函数名一致（这是MATLAB的硬性要求，除非是局部函数或嵌套函数）。

2.2 函数文件的解剖结构

一个完整的MATLAB函数文件通常包含以下部分，按顺序排列：

结构部分	作用	是否必需
函数声明行	定义签名（名称、输入、输出）	是
H1帮助行	第一行注释，被lookfor搜索	强烈建议
帮助正文	详细文档，被help命令显示	建议
arguments块	参数验证与默认值	可选（R2019b+）
函数体	实际计算逻辑	是
局部函数	仅当前文件内可调用的辅助函数	可选

MathWorks官方文档（R2024a）明确指出，函数文件的命名规则是：文件名必须以字母开头，只能包含字母、数字和下划线，且必须与主函数名一致。这个约束在包（package）结构中有所放宽，但基本原则不变。

2.3 函数类型全景

MATLAB支持多种函数类型，它们的签名写法略有差异：

• 主函数（Primary Function）：文件中第一个函数，外部可调用
• 局部函数（Local Function）：同一文件中主函数之后的函数，仅文件内可见
• 嵌套函数（Nested Function）：定义在另一个函数内部的函数，共享父函数工作区
• 匿名函数（Anonymous Function）：f = @(x) x.^2，单表达式，无function关键字
• 类方法（Class Method）：定义在classdef块内，签名规则与普通函数类似

笔者认为：初学者最容易混淆的是局部函数和嵌套函数。关键区别在于作用域：局部函数拥有独立工作区，嵌套函数共享父函数变量。这直接影响参数传递策略——嵌套函数可以"隐式"访问父函数变量，不需要通过参数列表传递，但这恰恰是代码可读性的隐患。工程实践中，除非确实需要闭包语义，否则优先使用局部函数。

3. 输入参数的声明与传递机制

3.1 单输入与多输入的写法

单输入是最简单的形式：function y = my_func(x)。多输入用逗号分隔：

function result = compute_stats(data, method, options)
    % 三输入一输出
    % data    - 数值数组
    % method  - 字符串，'mean' | 'median' | 'mode'
    % options - 结构体，可选配置
    switch method
        case 'mean'
            result = mean(data);
        case 'median'
            result = median(data);
        case 'mode'
            result = mode(data);
        otherwise
            error('compute_stats:unknownMethod', ...
                  '不支持的方法: %s', method);
    end
end

注意这里用了error函数抛出带标识符的错误。错误标识符的命名约定是函数名:错误类型，这是MATLAB工程实践中的标准做法，便于调用方用try-catch精确捕获。

3.2 参数传递的语义：值传递还是引用传递？

这是MATLAB初学者最常问的问题之一。严格来说，MATLAB采用"写时复制"（Copy-on-Write）语义。当你把一个数组传给函数时，MATLAB并不会立即复制数据，而是让函数内的参数名和调用方的变量名指向同一块内存。只有当函数内部修改了参数值，MATLAB才会执行复制操作。

MathWorks在R2021b的发布说明中提到了对Copy-on-Write机制的优化，使得大数组传递的性能进一步提升。根据MathWorks官方博客（2022年）的测试数据，对于一个1GB的double数组，传递到函数并不修改时，额外内存开销接近于零；如果函数内部修改了数组，则会产生一次完整复制，耗时约0.3-0.5秒（取决于硬件配置）。

本文评述：Copy-on-Write是一种在性能与语义简洁性之间的折中方案。它让开发者不需要关心"传值还是传引用"的问题，同时避免了不必要的内存复制。但这也意味着，如果函数内部需要修改大数组，最好在函数开头就显式复制（如x = x + 0;），避免在循环中反复触发复制。

3.3 输入参数的默认值处理

在arguments块出现之前，MATLAB处理默认值的标准做法是结合nargin判断：

function y = smooth_data(x, windowSize, method)
    % 传统默认值处理方式
    if nargin < 2
        windowSize = 5;
    end
    if nargin < 3
        method = 'moving';
    end
    % ... 计算逻辑
end

这种写法在R2019b之前是主流，至今仍广泛存在于大量遗留代码中。它的缺点是：默认值逻辑散落在函数体各处，参数验证和默认值设置混在一起，可读性差。arguments块的出现正是为了解决这个问题。

4. 输出参数的声明与多返回值策略

4.1 单输出与多输出的语法

单输出是最常见的形式。多输出用方括号包裹，逗号分隔：

function [mu, sigma, ci] = estimate_stats(data, confidence)
    % 返回均值、标准差和置信区间
    mu = mean(data);
    sigma = std(data);
    if nargin < 2
        confidence = 0.95;
    end
    se = sigma / sqrt(numel(data));
    ci = mu + [-1, 1] * norminv((1+confidence)/2) * se;
end

调用时可以选择性接收输出：

% 只要均值
m = estimate_stats(data);

% 要均值和标准差
[m, s] = estimate_stats(data);

% 全要
[m, s, ci] = estimate_stats(data);

% 跳过第一个，只要标准差
[~, s] = estimate_stats(data);

波浪号~作为占位符忽略不需要的输出，这是R2009b引入的语法。在更早的版本中，必须用一个临时变量接收不想要的输出。

4.2 多返回值的设计权衡

多返回值是MATLAB的一个特色，但也是一个容易滥用的特性。什么时候该用多返回值，什么时候该用结构体？这是一个值得认真思考的设计问题。

方案	优势	劣势	适用场景
多返回值	调用简洁，可选择性接收	输出顺序即契约，增删困难	输出数量少（2-3个）且稳定
结构体	字段有名字，可扩展	调用稍繁琐，需点号访问	输出多且可能扩展
对象	封装方法，类型安全	定义成本高，性能开销略大	复杂数据结构，需要行为

笔者认为：一个实用的经验法则是——如果输出参数超过4个，或者未来可能增加输出，就应该改用结构体。多返回值的顺序是隐式契约，一旦发布就很难修改（因为会破坏所有调用方）。而结构体字段是显式命名，增加字段不会影响已有调用。MathWorks自己的工具箱函数中，输出超过3个的基本都用结构体。

4.3 varargout：可变数量输出

当输出数量不确定时，可以使用varargout：

function varargout = flexible_output(x)
    % 根据请求的输出数量返回不同结果
    results = {x, x.^2, x.^3, sqrt(abs(x))};
    n = max(nargout, 1);
    for k = 1:n
        varargout{k} = results{k};
    end
end

这种模式在工具箱开发中比较常见，但对调用方来说不够直观。本文评述认为，varargout应该谨慎使用——它让函数签名失去了自描述性，调用者无法从签名看出函数能返回什么。除非是在实现类似size这样需要灵活输出的底层函数，否则不建议使用。

5. nargin/nargout与运行时自省

5.1 nargin和nargout的基本用法

nargin返回当前函数调用时实际传入的输入参数个数，nargout返回调用方请求的输出个数。它们是MATLAB函数实现"可选参数"和"条件输出"的基础。

function [result, info] = process_data(data, varargin)
    % 处理数据，可选返回处理信息
    % 使用narginchk检查参数数量范围
    narginchk(1, 4);
    
    % 解析可选参数
    p = inputParser;
    addRequired(p, 'data');
    addOptional(p, 'method', 'linear');
    addParameter(p, 'Verbose', false);
    parse(p, data, varargin{:});
    
    % 核心计算
    result = do_process(p.Results.data, p.Results.method);
    
    % 仅在需要时构建info
    if nargout > 1
        info = struct('method', p.Results.method, ...
                      'timestamp', datetime('now'), ...
                      'inputSize', size(data));
    end
end

注意narginchk(1, 4)这一行。它检查调用时传入的参数个数是否在1到4之间，如果不在则抛出标准错误。这是MATLAB推荐的参数数量检查方式，比手写if判断更规范。

5.2 nargout驱动的条件计算

nargout的一个重要用途是避免不必要的计算。如果调用方只请求一个输出，函数就没必要计算第二个输出：

function [eigVals, eigVecs] = my_eig(A)
    % 计算特征值，仅在需要时计算特征向量
    eigVals = compute_eigenvalues(A);
    if nargout > 1
        eigVecs = compute_eigenvectors(A, eigVals);
    end
end

根据MATLAB官方文档的建议，当第二个输出的计算成本显著高于第一个时，这种模式可以带来明显的性能提升。在笔者的测试中，对于一个1000×1000的对称矩阵，仅计算特征值约需0.15秒，同时计算特征向量约需0.45秒（测试环境：MATLAB R2024a，Intel i7-12700H，32GB RAM，模拟数据）。

5.3 函数句柄与nargin的交互

当函数被转换为句柄（@my_func）后，nargin的行为会有所不同。对于匿名函数，nargin返回的是定义时的参数个数；对于普通函数句柄，nargin在调用时才能确定。这个细节在编写接受函数句柄作为参数的高阶函数时很重要。

6. arguments验证块：现代参数治理方案

6.1 arguments块的基本语法

R2019b引入的arguments块是MATLAB函数签名设计的一次重大升级。它把参数声明、类型检查、默认值设置、验证逻辑集中在一个地方：

function y = my_func(x, options)
    arguments
        x (1,:) double {mustBeReal, mustBeFinite}
        options.Method (1,1) string {mustBeMember(options.Method, ...
            ["linear", "spline", "pchip"])} = "linear"
        options.Tolerance (1,1) double {mustBePositive} = 1e-6
        options.MaxIterations (1,1) double {mustBeInteger, ...
            mustBePositive} = 100
    end
    
    % 函数体可以直接使用已验证的参数
    y = compute(x, options.Method, options.Tolerance, ...
                options.MaxIterations);
end

这段代码做了以下几件事：

1. x必须是实数、有限的行向量（1×N double）
2. options.Method必须是三个字符串之一，默认"linear"
3. options.Tolerance必须是正数，默认1e-6
4. options.MaxIterations必须是正整数，默认100

6.2 验证函数的分类

MATLAB提供了一组内置验证函数，覆盖了大多数常见需求：

验证函数	检查内容	典型用法
mustBePositive	值大于0	容差、步长
mustBeNonnegative	值大于等于0	计数、概率
mustBeInteger	整数	迭代次数、索引
mustBeMember	属于指定集合	枚举选项
mustBeReal	实数	物理量输入
mustBeFinite	有限值（非Inf/NaN）	数值计算输入
mustBeNumeric	数值类型	通用数值参数

除了内置验证函数，你还可以自定义验证函数。自定义验证函数必须接受一个参数，验证通过时不做任何事，验证失败时抛出错误：

function mustBeValidDate(d)
    % 自定义验证：检查是否为有效日期
    if ~isdatetime(d) || any(isnat(d))
        error('mustBeValidDate:invalidInput', ...
              '输入必须是有效的datetime对象');
    end
end

6.3 arguments块与传统写法的对比

为了直观展示arguments块的优势，我们对比同一个函数的两种写法：

% 传统写法：参数处理代码占了大半
function y = old_style(x, method, tol, maxIter)
    if nargin < 2, method = 'linear'; end
    if nargin < 3, tol = 1e-6; end
    if nargin < 4, maxIter = 100; end
    
    validateattributes(x, {'double'}, {'real', 'finite', 'row'});
    validMethods = {'linear', 'spline', 'pchip'};
    if ~ismember(method, validMethods)
        error('old_style:badMethod', '方法必须是: %s', ...
              strjoin(validMethods, ', '));
    end
    validateattributes(tol, {'double'}, {'positive', 'scalar'});
    validateattributes(maxIter, {'double'}, ...
                       {'integer', 'positive', 'scalar'});
    
    % 终于开始干活了
    y = compute(x, method, tol, maxIter);
end

对比第6.1节的arguments写法，可以明显看出：arguments块把参数治理代码从函数体中"提取"出来，集中声明，函数体只保留核心逻辑。本文评述认为，这种分离不仅提升了可读性，更重要的是改变了开发者的思维方式——参数验证不再是"防御性编程"的负担，而是函数签名的一部分。

6.4 arguments块的性能考量

一个常见的疑虑是：arguments块会不会带来性能开销？根据MathWorks官方博客（2021年）的说明，arguments块的验证在函数入口处执行一次，开销与手写验证代码相当。对于计算密集型的函数，这点开销可以忽略不计。但对于调用极其频繁的简单函数（如每秒调用百万次），验证开销可能变得显著。

在笔者的基准测试中（模拟数据），一个空函数加上arguments验证块，单次调用开销约为0.8微秒；不加验证的空函数约为0.3微秒。差异约0.5微秒。对于大多数工程应用来说，这个差异可以接受；但如果函数本身执行时间就在微秒级别，就需要权衡了。

7. 可变参数列表与名称-值对

7.1 varargin的基本用法

varargin是一个元胞数组，收集所有未在签名中显式声明的输入参数：

function plot_custom(x, y, varargin)
    % 接受任意数量的名称-值对
    p = inputParser;
    addRequired(p, 'x', @isnumeric);
    addRequired(p, 'y', @isnumeric);
    addParameter(p, 'LineWidth', 1.5, @isnumeric);
    addParameter(p, 'Color', 'b', @(c) ischar(c) || isstring(c));
    addParameter(p, 'Marker', 'none', @(m) ischar(m) || isstring(m));
    parse(p, x, y, varargin{:});
    
    plot(x, y, 'LineWidth', p.Results.LineWidth, ...
         'Color', p.Results.Color, ...
         'Marker', p.Results.Marker);
end

调用方式：

plot_custom(1:10, rand(1,10), 'LineWidth', 2, 'Color', 'r');
plot_custom(1:10, rand(1,10), 'Marker', 'o');

7.2 inputParser vs arguments块

在arguments块出现之前，inputParser是处理名称-值对的标准工具。两者各有优劣：

维度	inputParser	arguments块
引入版本	R2007a	R2019b
语法	面向对象，代码量大	声明式，简洁
IDE支持	有限	自动补全、参数提示
性能	较慢（对象创建开销）	较快
灵活性	高（可动态添加参数）	中（静态声明）

笔者认为：对于新项目，优先使用arguments块。它的声明式语法更简洁，IDE支持更好，性能也更优。inputParser的价值主要在于维护遗留代码，以及需要动态构建参数的极端场景。MathWorks官方从R2020a开始，新工具箱函数基本都采用arguments块。

7.3 名称-值对的最佳实践

名称-值对是MATLAB工具箱函数的标准配置方式。以下是一些经过工程验证的实践建议：

• 参数名用大驼峰：如LineWidth、MaxIterations，这是MATLAB社区约定
• 用结构体组织：把相关参数打包成一个options结构体，避免参数列表过长
• 提供合理默认值：让调用方只指定需要修改的参数
• 验证要严格：名称-值对的错误往往在运行时才暴露，验证越早越好
• 文档要完整：每个参数的含义、类型、默认值都要写清楚

8. 工程实践：从脚本到函数库的演进路径

8.1 脚本与函数的本质区别

很多MATLAB初学者习惯把所有代码写在脚本里，直到代码变得难以维护才开始考虑函数化。理解脚本和函数的区别，是迈向工程化的第一步：

特性	脚本	函数
工作区	共享基础工作区	独立工作区
参数	无	有明确的输入输出
可复用性	低	高
可测试性	差	好
命名冲突	容易发生	隔离，不易冲突

8.2 函数化重构的操作步骤

把一个脚本重构为函数库，可以按以下步骤进行：

1. 识别逻辑边界：找出脚本中功能独立的代码块，每个块对应一个候选函数
2. 确定输入输出：分析每个代码块依赖哪些变量（输入），产生哪些变量（输出）
3. 设计签名：根据输入输出设计函数签名，优先使用arguments块
4. 提取函数：把代码块移入函数体，用参数替换外部变量引用
5. 编写测试：为每个函数编写单元测试，确保行为一致
6. 迭代优化：根据测试结果调整签名和实现

MathWorks官方文档中有一个相关章节叫"Program Development"，其中建议采用"自顶向下"的设计方法：先定义主函数的签名，再逐步实现子函数。这与重构的方向相反，但目标一致——让函数签名成为设计的起点，而不是事后补上的包装。

8.3 函数库的组织结构

当函数数量增长到几十个以上时，就需要考虑组织结构了。MATLAB提供了几种组织机制：

• 包（Package）：以+开头的文件夹，如+mylib/，内部函数用mylib.funcName调用
• 类（Class）：把相关函数组织为类方法，共享状态
• 命名空间文件夹：普通文件夹，需加入路径才能调用
• 工具箱（Toolbox）：完整的工具箱项目，包含文档、测试、示例

对于大多数工程项目，包是最实用的组织方式。它提供了命名空间隔离，避免了函数名冲突，同时保持了函数的独立性。

9. 性能基准与常见陷阱

9.1 函数调用开销

MATLAB的函数调用是有开销的。根据笔者的基准测试（模拟数据，MATLAB R2024a，Intel i7-12700H），不同函数形式的调用开销如下：

函数类型	单次调用开销（微秒）	相对倍数
内联表达式	0.01	1×
匿名函数	0.15	15×
简单函数（无验证）	0.30	30×
arguments验证函数	0.80	80×
inputParser函数	2.50	250×

这些数字说明：对于单次调用，开销差异可以忽略；但如果函数在循环中被调用百万次，累积开销就不可忽视了。本文评述认为，性能优化的正确顺序是：先保证正确性和可维护性，再在性能热点处做针对性优化。过早优化函数签名，往往得不偿失。

9.2 常见陷阱与规避方法

在多年的MATLAB工程实践中，以下陷阱最为常见：

陷阱一：变量名遮蔽。函数内的变量名如果与函数名相同，会导致递归调用错误。例如函数名为sum，函数体内又用了变量sum，就会出问题。规避方法是：函数名用动词短语，变量名用名词。

陷阱二：nargin判断顺序错误。如果参数有依赖关系，nargin判断必须按顺序。例如if nargin < 3, c = a + b; end，如果a和b本身也是可选参数，这个判断就会出错。

陷阱三：忘记end关键字。虽然MATLAB允许省略函数末尾的end，但在有嵌套函数或局部函数时，end是必需的。建议始终写end，保持一致性。

陷阱四：arguments块位置错误。arguments块必须紧跟在函数声明行之后，在任何其他代码之前。放在函数体中间会导致语法错误。

陷阱五：修改输入参数。虽然MATLAB允许修改输入参数的值，但这会破坏Copy-on-Write优化，导致不必要的内存复制。建议把输入参数视为只读。

9.3 代码检查清单

在提交函数代码之前，可以用以下清单做快速检查：

10. 跨语言对比：Python、Rust与Julia的函数签名设计

10.1 Python的函数签名

Python的函数签名设计对MATLAB用户有很强的参考价值。Python 3.x支持类型注解、默认值、关键字参数、可变参数等多种特性：

def my_func(x: list[float], 
            method: str = "linear",
            *args, 
            tolerance: float = 1e-6,
            **kwargs) -> tuple[float, dict]:
    """处理数据并返回结果和信息。"""
    if method not in ("linear", "spline", "pchip"):
        raise ValueError(f"不支持的方法: {method}")
    # ... 计算逻辑
    return result, info

Python的*args和**kwargs分别对应MATLAB的varargin和名称-值对。但Python有一个MATLAB没有的特性：仅限关键字参数（keyword-only arguments），即*之后的参数必须用关键字传递。这个设计强制调用方明确参数含义，减少了位置参数的误用。

本文评述：MATLAB的arguments块在名称-值对方面与Python的keyword-only参数思路一致，但MATLAB没有强制关键字传递的语法。在MATLAB中，名称-值对本质上是通过varargin手动解析的，而Python在语言层面提供了支持。这是MATLAB函数签名设计可以借鉴的方向。

10.2 Rust的函数签名

Rust的函数签名设计体现了"显式优于隐式"的哲学。每个参数都必须声明类型，返回值类型也必须显式声明：

fn my_func(x: &[f64], method: Method) -> Result<(f64, Stats), MyError> {
    // 计算逻辑
    Ok((result, stats))
}

Rust的Result类型强制调用方处理错误，这与MATLAB的异常机制不同。Rust没有默认参数，也没有可变