Ever looked at a flow, formula field or other metadata and asked yourself what the hell it’s supposed to do?

Enter the Description field on Salesforce metadata. You should look at it like code comments, but for metadata.

Experienced developers know that good comments help whoever has to work on their code in the future. And since that unlucky person could be you, it’s worth actually writing them once in a while!

Comments are often neglected, but not as often as the Description field. And I want that to change. This field lets you explain what you’ve built, and why.

The use cases are endless. It’s always helpful to explain:

• The business logic behind a formula field
• Which records should fail a validation rule
• What data a field should contain, and how it gets populated
• Which user story this relates to
• Why you’ve done something counter-intuitive
• Which dependencies your metadata has (or what’s dependent on your metadata)

But not all comments are useful.

What are ‘useful’ comments?

Building on the comments analogy, we can learn from decades of ~arguments~ discussions about what makes for useful comments.

Here’s a summary of the recommendations from Clean Code by Robert Martin:

• Always try to explain yourself in code.
• Don’t be redundant.
• Don’t add obvious noise.
• Don’t use closing brace comments.
• Don’t comment out code. Just remove.
• Use as explanation of intent.
• Use as clarification of code.
• Use as warning of consequences.

What does that mean in practice?

If your validation rule is called Middle Name must be populated, don’t add the description Checks that the middle name is populated That’s redundant and useless.

Something like this might be more useful:

Accounts coming from system X should be rejected if this field is missing. This enables business process Y and avoids problems with automation rule Z. The admin team manually reports on failures to identify and fix any issues. See JIRA-12345 for details.

A year from now, when a production deployment is failing and you’re considering disabling this validation rule to fix it, this description might help you think twice.

So what?

So please, do yourself a favour: next time you see an empty Description field, add some useful comments.

Better yet, set up your static code analysis tools to check for this as a code quality metric, so that it becomes a standard practice on your team.

Last modified on 2021-07-19