Provide good example and rationale behind the rule

[rbuchmann77]

Version 2.4.0

Robocop print warnings and errors given rules. When we read those warnings and errors, sometimes it is hard to understand why there is this rule or how to fix it in a proper way.

For example:
https://robocop.readthedocs.io/en/stable/rules.html#comments

We would like to add a "TODO: do not forget to do this and this." in my code. Robocop print the warning "todo-in-comment". I check the documentation and I do not understand why.

For example, I moved the line from the test cases section to the header and still have the warning. Yes, I'm trying (silly ?) things.

I have no doubt this warning is useful. Checkers/linters are wonderful tools to learn best practices. For example, I really love shellcheck for this help to the learning process:
https://www.shellcheck.net/wiki/SC1118

Is it possible to add to the robot documentation the rationale and a good example to follow?

[bhirsz]

It's a good idea - it's one of the reasons why I've recently extended our docs with the ability to add such extended docs (previously all our external docs were automatically generated without examples). One of the examples where we put "why this rule exist" is https://robocop.readthedocs.io/en/stable/rules.html#tag-with-or-and .

However there are currently workshops ongoing that are trying to create Robot Framework official style guide - it's very likely that some of our rules will be updated/reworded to match official style guide. When it will happen I will try to also reuse examples from style guide in our documentation (or link directly from the Robocop rule to style guide rule/recommendation).

But I will take a look into our rules and try to update missing docs in the meantime too. There are still several rules that are missing examples / reasons for existence.

[bhirsz]

And to comment on the rule mentioned in your post - TODO in the comments is fine and Robocop rule for discovering it is just a handy tool to see any TODO/FIXMEs in your code. You can't "fix" it by moving the comment, the only way of "fixing" it is resolving TODO task :). But we could use this extra explanation in our docs - that it's just visual guidence for users to see all of their TODOs, not necessarily rule prohibiting using TODO in the comment.

[mnojek]

I think we should revisit the documentation for each rule and provide more meaningful, real-world examples, to make it easier for the users to understand how to use the rules. Currently, in many places, we have some generic sample code which has nothing to do with the code that is produced in a real environment.

It'll take time, because it's not that easy each time to come up with a good example, but I think it's worth doing. Again, we can split the work here, @bhirsz. Also, it's not very urgent, so we can do it gradually.

[bhirsz]

I agree on doing the review and we should split the work

[mnojek]

2 out of 9 rule categories were updated in #917:

• naming
• documentation