Overview
This rule flags metadata elements such as Custom Fields, Custom Objects, and Flows that lack descriptions. While these elements may function correctly, missing documentation makes it harder for developers, admins, and analysts to understand their purpose, increasing the risk of misuse and duplication.
Code Reviews classifies this as a Warning because it doesn’t immediately impact performance or functionality, but it significantly reduces system transparency and long-term maintainability.
Why This Matters
Clear descriptions provide essential context, improve transparency, and foster better collaboration, contributing to a more maintainable and scalable Salesforce environment.
Obscured Purpose: Without descriptions, the intended function of metadata elements becomes unclear to team members who didn't create them. This can lead to misuse or incorrect assumptions about their behavior.
Slowed Onboarding: New administrators or developers face a steeper learning curve when metadata lacks context, as they must spend extra time deciphering existing configurations.
Increased Duplication: When the purpose of existing elements is unknown, teams may inadvertently recreate redundant functionality, leading to a bloated and less efficient org.
Troubleshooting Difficulties: Debugging issues becomes more complex and time-consuming when it's unclear how a metadata element was designed to function.
Hinders Auditing: Lack of proper documentation makes it challenging to perform audits or compliance reviews, as the business rationale for each element is not readily available.
Reduced Collaboration: Poorly documented metadata acts as a barrier to effective teamwork, slowing down development cycles and increasing the risk of errors due to misunderstandings.
What Triggers This Rule
The rule specifically checks the Flow's underlying XML metadata file for the presence and content of the <description> tag.
Recommended Approach
To maintain a well-documented and understandable Salesforce org, you should add clear, concise descriptions to all custom metadata elements: for Custom Fields, explain what the field tracks and its purpose, like "Tracks whether the customer's subscription has been renewed, expired, or is pending" for Renewal_Status__c; for Custom Objects, describe the business process or data model they support and for Flows, summarize their trigger, purpose, and key outcomes, such as "Automatically updates renewal status and creates a case when a contract is expiring within 30 days" for AutoRenewalTrigger.
Summary
Well-documented metadata makes your org easier to understand, maintain, and scale. Add descriptions to custom fields, objects, and Flows to reduce confusion and support team collaboration. Code Reviews flags missing descriptions as a Warning to promote clarity and metadata hygiene.