Table of Contents

可见对象应有描述

  • 2026-01-09
  • Morten Lønskov

概述

此最佳实践规则会识别缺少描述的可见表、列、度量值、计算组以及用户定义函数。 添加描述可提升模型的易用性、文档质量和用户体验。

  • 类别：维护

  • 严重性：低（1）

适用于

  • 表
  • 计算表格
  • 数据列
  • 计算列
  • 计算表格列
  • 度量值
  • 计算组
  • 用户定义函数（兼容级别 1702+）

为何重要

描述可为模型用户提供关键背景信息：

  • 提升可发现性：用户在使用字段之前就能了解其用途
  • 增强自助式 BI：业务用户在清晰指引下即可独立开展分析
  • 降低支持负担：关于字段定义的疑问更少
  • 增强的工具提示：Power BI 和 Excel 会在悬停时的工具提示中显示描述
  • 文档基础：描述是自动化文档的基础
  • 治理与合规：描述可包含数据血缘和业务定义
  • AI 使用：如果对象包含说明，AI 代理能更准确地推断其用途。 如果没有描述，用户只能猜测字段含义，导致分析错误，并增加支持请求。

此规则何时触发

当对象可见且描述为空或仅包含空白字符时，此规则将触发：

string.IsNullOrWhitespace(Description)
and
IsHidden == false

注意：已隐藏的对象会被排除，因为它们并不面向最终用户使用。

如何修复

手动修复

  1. 在 TOM Explorer 中，选择该对象
  2. 在 属性 窗格中，找到 描述 字段
  3. 输入清晰、简明的描述
  4. 保存更改

常见原因

原因 1：开发阶段缺少文档

创建对象时未添加描述。

原因 2：快速原型开发

为快速搭建模型而未进行适当的文档编写。

原因 3：遗留模型

在描述标准建立之前创建的旧模型。

示例

修复前

度量值：[Total Revenue]
描述：（空）

用户体验：工具提示不显示任何内容，用户必须猜测该度量值的用途。

修复后

度量值: [Total Revenue]
说明: "不含税费和折扣的总收入。计算为 SUM(Sales[UnitPrice] * Sales[Quantity])。用于财务报告。"

用户体验：清晰的工具提示可帮助用户理解并正确使用该度量值。

兼容级别

本规则适用于兼容级别为 1200 及以上的模型。

兼容级别达到 1702 及以上时，会验证用户定义函数的说明。

相关规则