Question

我在matlab中编写了一个简单的标记管理器类，我正在努力（或者可能过度思考;-)并适当地命名我的类方法。该类称为tag_manager。以下是关于明确的API和实现的问题：

如果要添加标记，我应该调用方法add还是add_tag？同样适用于删除。
如果要重命名代码，我应该调用方法rename_tag还是rename？

我总是想添加_tag后缀，以便明确方法的作用。

nbr_tags是一个计数器，用于跟踪当前存储的标记数量。我有时需要访问这个数字，所以我没有通过标签列表并计算条目数，而是想通过类方法返回这个值。 return_nbr_tags是可行的，还是可以更简洁地命名？
通常，我需要知道标记的索引，而标记又用于查找某些其他矩阵中的某些元素。为了防止代码变长，我简单地称这个方法inx()，它应该是return_tag_index的缩写。我知道今天我确实知道inx()代表什么，但是从现在开始的两周内我可能无法记住。那么命名这些方法的最佳方法是什么？

这是类定义：

properties (SetAccess = private, GetAccess = public)
    tag_names = {}; % store the tags
    tag_rel_indx = []; % the relative tag index
    tag_abs_indx = []; % the absolute tag index
end

properties (SetAccess = private, GetAccess = public, Hidden = true)
    nbr_tags = 0;
    abs_tag_counter = 0;
end

methods
    % add single tag to list. should be 'add' or 'add_tag'?
    function obj = add_tag(obj, name)
    end

    % remove single tag from list
    function obj = remove_tag(obj, name)
    end

    % short-cut for 'return_tag_index'
    function indx = inx(obj, name)
        indx = return_tag_index(obj, name);
    end

    % rename tag
    function obj = rename_tag(obj, old_name, new_name)
    end

    % re-order tags by name
    function obj = reorder_by_name(obj)
    end

    % return number of tags stored in tagmanager
    function nbr_tags = return_nbr_tags(obj)
        nbr_tags = obj.nbr_tags;
    end

end

非常感谢！

Answer 1

在我看来，以前不得不使用其他人的代码，当方法/功能名称清晰且具有描述性时，我发现它非常有用。我更倾向于有人用他们的功能名称来详细说明，但同时你也不想过于冗长。

例如，您的标签返回功能。我个人会说GetNumberOfTags之类的东西。对于我用来设置特定值的函数，我使用SetParticularValue。

但是，我确实远离下划线。这可能只是我从工作中的编码实践中汲取的习惯。

最重要的是要记住整个班级的一致性。并且如果函数不完全清楚，不要忘记有用的注释= P当你必须回过头来重新编写某个人的代码并且有一个关于什么变量被用于什么以及函数是什么的真实信息时，这太可怕了真的是要做;）。

Answer 2

在使用高度显式的函数名称（这对于理解代码非常有用）和创建易于开发和使用的代码之间总是需要权衡。如果您需要为方法创建快捷方式名称，则表明您已经转向显式函数名称。

在您的情况下，由于您正在创建标记管理器，我会从方法中删除tag，而是启动将标记管理器类实例化为tags = tagManager;的约定，以便该方法添加标签的行为是tags.add(...)或add(tags,...)。但是，添加更明确的方法名称将有助于添加标签以外的其他内容，例如tags.addGroup。然后，您的索引方法变为index(tags,name)，在我看来，它既简短又清晰。

PS：为什么有returnNumberOfTags方法？您可以从属性中读取，并在必要时添加set / get方法。

以一致和精确的方式命名类方法

2 个答案: