Docs: Explicitly state a preference for messageId vs message in custom rules docs

[JoshuaKGoldberg]

Docs page(s)

https://eslint.org/docs/latest/extend/custom-rules

What documentation issue do you want to solve?

The ESLint Custom Rules docs describe the two ways to set the message text of a rule report:

• message (older): Directly allows setting message text
• messageId (added in New: Add context.report({ messageId }) (fixes #6740) #9165): Keys message texts to rule metadata

...but nothing in the docs page explicitly says which is preferable. I think this implies to developers that either is fine - despite the advantages of messageId mentioned in #6740 -> #9165.

What do you think is the correct solution?

I think the docs should state that messageIds are preferred for the reasons noted in #6740. A further example of the better tooling support is the set of lint rules in https://github.com/eslint-community/eslint-plugin-eslint-plugin that support them: eslint-plugin/no-missing-message-ids and eslint-plugin/no-unused-message-ids.

The eslint-plugin/prefer-message-ids rule is even enabled in the plugin:eslint-plugin/recommended preset.

Participation

• I am willing to submit a pull request for this change.

Additional comments

https://github.com/eslint-community/eslint-plugin-eslint-plugin is mentioned at the bottom of https://eslint.org/docs/latest/extend/plugins too:

eslint/docs/src/extend/plugins.md

Line 189 in ba87a06

* [eslint-plugin-eslint-plugin](https://www.npmjs.com/package/eslint-plugin-eslint-plugin)

That comes across to me as a recommendation to adhere to the plugin's recommendations.

[nzakas]

As with most things, we actually don't have a preference here, and I'm not sure it makes sense to state one.

I hesitate to be overly prescriptive as it leads us down the line of "well why have two ways to do things if you want us to use just one?"

But, I don't feel particularly strongly. If any other team members think this is worthwhile, I'm happy to go along.

[snitin315]

I don't have a strong opinion on preference here either.

[fasttime]

The docs section about messageId already indicates two reasons why messageId is preferable to message:

This allows you to avoid retyping error messages. It also prevents errors reported in different sections of your rule from having out-of-date messages.

Maybe we could elaborate on that description to include the other advantages noted in #6740 if they are still relevant. Rule developers would be able to take a more informed decision by themselves.

[bmish]

As the author of eslint-plugin/prefer-message-ids, I am in favor of offering a "recommendation" in the docs for messageId over message. Certainly not a requirement, but pointing out the benefits of message IDs, like the rule doc does, could help users decide between them:

• Rule violation messages can be stored in a central meta.messages object for convenient management
• Rule violation messages do not need to be repeated in both the rule file and rule test file
• As a result, the barrier for changing rule violation messages is lower, encouraging more frequent contributions to improve and optimize them for the greatest clarity and usefulness

[nzakas]

@bmish those are some good bullet points. I agree, let's add a recommendation for messageId. Do you want to take that?

[bmish]

Yes I'll open a PR: #18050