Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation of CSpell-supporting code annotations #231

Open
bugfolder opened this issue Nov 25, 2023 · 0 comments
Open

Add documentation of CSpell-supporting code annotations #231

bugfolder opened this issue Nov 25, 2023 · 0 comments

Comments

@bugfolder
Copy link
Contributor

Per backdrop/backdrop-issues#6302, there are several things we might be doing in code to support CSpell spell-checking, e.g.,

If the word exists only in a 3rd party library that we are using and never or very rarely change, then consider ignoring the entire file/path in the ignorePaths section of our .cspell/cspell.json configuration file. Using cspell:disable-next-line or cspell:disable/cspell:enable pairs in these cases is impractical, as we shouldn't be changing 3rd party code (we'll loose those ignores if the library is updated in the future).

If the word is non-English (testing Unicode for example), the preference will be to ignore it with cspell:disable-next-line, or with cspell:disable/cspell:enable pairs when dealing with multiple lines where these words occur.

If the failure is for existing variable/function names or comments, then try to fix/rename those where possible/practical instead of adding more words to our dictionary - especially when these words are used only say 2-3 times in our entire codebase.

If the failure is for newly-introduced words in the PR, then:

try to fix those (split any combined words with dashes or underscores, or use camelCase for example)
or, come up with alternative words that do not trip CSpell
or, if the word is a made-up, fictional word used for testing purposes or as a documentation example, then see any existing fictional/test words in our dictionary can be used instead (if you are calling the thing pigglywiggly for example, then rename it to foobar which we have already added to our dictionary).
or, if the word occurs multiple times in a single file, but you don't want to ignore the entire file, nor use dozens of cspell:disable-next-line, then consider ignoring the specific word(s) in the specific file, by adding an entry in the overrides section of our .cspell/cspell.json configuration file.
Again, the goal will be to avoid adding more words to our custom CSpell dictionary where possible.

When fixing the codebase is not practical/possible, new words may be added to the dictionary. This will be able to happen without any core commit once we have moved our custom dictionary to its dedicated repo in https://github.com/backdrop-ops/cspell (refer to backdrop/backdrop-issues#6280).

We should document CSpell-related code practices in our documentation, somewhere under Coding and documentation standards; perhaps adjacent to Naming Conventions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant