Dart dartdoc中{@template}与{@macro}注释的命名规范是什么

dartdoc模板与宏命名规范说明 #

目前dartdoc官方没有发布针对{@template}、{@macro}标记名称的强制性统一规范，唯一可参考的官方示例惯例为使用snake_case格式命名模板。

你当前采用的「项目名.类名.方法名点分隔snake_case」格式，已经是目前Dart社区广泛使用的最佳实践，核心优势有两点：

• 天然避免命名冲突：前缀带项目名的命名方式，不会和第三方依赖包中的模板名称重复，不会出现宏调用错配的问题
• 层级清晰易维护：通过点分隔的层级可以直接定位到模板所属的代码模块，后续修改、查找模板时不需要额外梳理关联关系

除此之外，社区还有几个通用的命名惯例可供参考：

• 全局公共模板可增加common/shared前缀标识，比如{@template project_name.common.http_error_desc}，和对应具体API的模板做区分
• 模板名仅使用小写字母、下划线、分隔用的点，不要使用特殊字符、大驼峰、短横线，避免触发dartdoc的解析异常
• {@macro}的调用名称和对应模板的命名规则保持一致即可，不需要单独调整规则

内容的提问来源于stack exchange，提问作者Valentin Vignal