search

canonical / praecepta

Creative Commons Attribution Share Alike 4.0 International
12 stars 20 forks source link

Add TODO to an avoidance list as a warning #78

Open izmalk opened 3 months ago

izmalk commented 3 months ago

Add a ToDo comment to a list of avoided terms with a warning. It should be case-insensitive (to cover all the variants: todo, TODO, ToDo).

ru-fu commented 2 months ago

Let's call that an ignore list or something. ;)

izmalk commented 1 month ago

Let's call that an ignore list or something. ;)

Actually, we should avoid using TODO in the docs (or at least highlight it as a potential error upon testing). We should not ignore it (at least automatically, like the vale tests). We can think of an alternative, for example, block list, reject list, or triggers. P.S. The idea is not exactly to ban usage of TODO at all, but rather make it more visible so we won't forget about it.

SecondSkoll commented 1 month ago

I think this is a good idea, with a caveat or two. I think if you have a "TODO" in your documentation it should be a known issue which requires work to be done. If a Jira issue has been created for the work to be done, then I think the TODO should be ignored automatically.

So some specific implementation of TODO: [JIRA-1234] <details> could be ignored, but other cases would raise errors.

This would mean any usage of "TODO" would either have a linked issue which requires work or raise an error - which would mean it could be easily noticed or tracked.

Thinking about general implementation of this rule (as I hope that we'll be able to provide our Vale style as a Vale package at some point) I think this rule should default to a suggestion, but then be overwritten by our vale.ini as is being suggested in #88.