Skip to content

Instantly share code, notes, and snippets.

@afred

afred/making_better_use_of_code_generators_in_hydra_gems.md

Created October 2, 2015 19:55
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save afred/085bfd8c12361dba0daa to your computer and use it in GitHub Desktop.
Save afred/085bfd8c12361dba0daa to your computer and use it in GitHub Desktop.
Download ZIP
Making better use of code generators in Hydra gems.
Raw
making_better_use_of_code_generators_in_hydra_gems.md

Making better use of code generators in Hydra gems.

The problem:

  • Code that is generated by a gem (configuration, templates, etc) is only guaranteed to work with the version of the gem that generated it.

  • Upgrading the gem may cause the previously generated code to become obsolete.

  • In some cases, the gem relies on the code created by it's generators in order to work as expected.

  • It is nice to provide upgrade scripts to handle this problem, but it's not always feasible.

    • Generated code may have diverged since original generation, and it's hard to programatically make decisions on how to reconcile those.

    • Upgrade scripts are not often a high priority, if they are in the project scope at all.

Deprecation warnings are helpful, but not enough

  • Deprecation warnings can only be applied to methods.
  • Deprecating configuration values is harder, and we don't have a standard way of doing it. E.g. how do you deprecate the use of a hash key, instance variable, a constant, etc.?
  • Deprecation handles the case of: "X will not be supported in the future", but does not handle the case of "you must now implement Y".

Strategies for better use of code generators:

Have the gem provide sensible defaults whenever possible

In other words, a gem should rely on the existence of local configuration as little as possible.

Many popular gems take the approach of generating a config file that is entirely commented, with lots of nice, human-readble explanations of what happens when you uncomment things.

If you don't like verbose config files that don't do anything, then another approach could be a minimal config file containing a link to a page that describes configuration options. Said page could even be the github URL for the file within the gem that contains the defaults configuration. That way the only documenation you'd have to keep up to date are the inline comments describing the default configuration, which should be up-to-date as a result of updating the code.

Provide better exception handling around invalid or missing configuration

It's ok for a gem to have reasonable expectations about how it is used. But when those expectations are not met, then the gem should be clear about what has gone wrong.

It is very frustrating (and time consuming) when a simple misconfiguration causes some seemingly unrelated exception to be thrown from deep within the callstack, hundreds of lines of code away from where the fix needs to be made.

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