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

Use human readable key value pairs for configuration. #47

Closed
cirosantilli opened this Issue Aug 15, 2014 · 4 comments

Comments

Projects
None yet
2 participants
@cirosantilli
Contributor

cirosantilli commented Aug 15, 2014

Instead of the MDXXX ids, why don't we use human readable key value pairs like:

unordered_list_marker: '*'

Advantages:

  • human readable: people can just read the config file directly to determine the style. Currently, you would have to look up what every rule means, or use comments, which generates a lot of explanation. Same reason why we use nice var names in the code.
  • pairs: deal nicely with mutually exclusive options like choosing one header or list style, in which enforcing multiple rules should never be done. Would solve: #38

Disadvantage: longer to type. But this is not serious, since projects will write a config file and seldom modify it, and for interactive use according to personal preferences one can just alias it or we can add a global config. Being able to read quickly is more important in this case.

This is what the popular Rubocop does: https://github.com/bbatsov/rubocop/blob/master/config/default.yml.

This could be implemented in either Ruby or YAML: I'd rather have YAML since it allows us not to write rule directives all the time and since the config is mostly static, but this is no big deal.

Also once we fix those things we should document it. I had to Google and grep a bit to figure it out =) #41

@mivok

This comment has been minimized.

Collaborator

mivok commented Aug 15, 2014

I'm not sure how I feel about not having a numeric ID for rules, but the two arguments I have in favor of them (easier to type and refer to in chat/IM/issues, and no need to change the ID later if the name doesn't make sense any more, such as if I'd named MD007 'multimarkdown_list_indent' before discovering another reason for wanting 4 space indents) aren't that strong. The inspiration for this way of doing things btw is Foodcritic rather than rubocop. It's interesting to see the different choices made between the two.

I do really like the idea of having rules be able to take parameters in style files, and it does neatly solve the issue of multiple rules that do essentially the same thing as well as conflicts.

mivok added a commit that referenced this issue Aug 23, 2014

Add support for rule parameters
Refs #47

Rule parameters are settings that can be passed to rules in style files in
order to customize their behavior. The settings are provided in style files to
enforce a specific style.

This commit also changes how ruleset files are evaluated to be more sensible
(the block inside the rule is now instance_eval's as part of the Rule object
rather than as part of the ruleset object and building up parts of the rule as
needed).
@mivok

This comment has been minimized.

Collaborator

mivok commented Aug 23, 2014

Parameters are done and in a branch. They'll be merged once I clean up the rules to use them.

However, regarding rule names, I think I'm still going to come down on the side of
having a short, mostly numeric, identifier for all rules. I've thought about
it quite a bit and there are two other issues I came across while trying out
named rules:

  • Some of the later rules will end up with rule names almost as long as the
    descriptions in order to fully specify what they do (e.g. multiple spaces
    inside hash on atx_closed headers), and while parameters have helped with some
    of those (the header style rule description is much more concise), it won't
    help everywhere.
  • Remembering the name of the rule without looking it up is more difficult than
    remembering a shorter number (e.g. was the rule name
    header_trailing_blank_line, header_surround_blank_lines or something else).

Both of these could be solved with aliases, but that sacrifices
recognizability of a given rule, especially if more terse forms are used, and
you're right back to the original issue that prompted having.

Ultimately, the tradeoff is reading and recognizing (in style files or other
places where it won't have the description printed next to the ID) vs writing
and remembering.

@cirosantilli

This comment has been minimized.

Contributor

cirosantilli commented Aug 23, 2014

I understand the difficulty, and of course the final decision is up to you.

I believe:

  1. When writing the config file: both numbers and meaningful names are hard enough to remember that people writing the config file will have to look up the docs in both cases for a very long time before they are confident enough with them to write the config without checking.
  2. When reading:
    • for readable IDs, you might have to look a few times at the docs, but it is likely that you will soon be able to guess correctly what they mean.
    • for numbers, readers will have to look at the docs for way longer before they memorize what they mean. They could always add comments to the config file, but then why not use the comment strings as data instead of the IDs?

People will read the files much more than they write them, since every contributor has to read it to know what style to use, but only a few owners will modify the file occasionally.

mivok added a commit that referenced this issue Aug 23, 2014

Use parameters for existing rules
Refs #47

This removes duplicates rules (e.g. enforcing specific header styles which can
now be configurable), updates the rule documentation and tests appropriately.
@mivok

This comment has been minimized.

Collaborator

mivok commented Aug 23, 2014

The rule parameters option has been merged. As part of this, I updated the style files to not have to exclude the rules that have now been removed. As part of this, I simplified the cirosantilli style file significantly. Let me know if the changes make sense or not.

For now I'm closing this issue. Docs on creating style files/rules/parameters I'll add as a separate issue.

@mivok mivok closed this Aug 23, 2014

@mivok mivok removed the on deck label Aug 23, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment