This is the sixth rule of my Guide to authoring Lua modules.
None of the previous 5 rules is absolute. Occasionally, the best course of action is to ignore them.
This rule acknowledges that. But this doesn’t mean you have carte blanche to break any rule at any moment. The complete text of this rule is this:
Break the rules when you have a good reason, and say it
The rule says that you must justify every breakage with a good reason. But which reasons are good?
Good reasons are based on objective, testable or measurable evidence - and on occasion they are accompanied by palliative actions.
- “I ignored rule #1 and used under-scored names since that’s the convention in my team”
- “I’m not returning a table on this module (rule #2) because it’s part of an internal package; I don’t need meta fields here, just a single function”
- “The performance tests for the typical case of this function run 40% faster if I localize this reference, so I’ll disallow monkeypatching here and use locals”
- “We are storing state on this module as a quick-and-dirty hack to get things ready for next week’s presentation. We’ve scheduled a refactoring to move the state to the application later”
Bad reasons, on the other hand, are subjective, based in the unknowns, or just plain lazy. They take no remedial actions:
- “I just don’t like monkeypatching” – subjective, goes against other rules (do what Lua does).
- “I don’t know how to implement this module without state (rule #4)” (based in unknowns, lazy)
- “I don’t have time to apply this” (no remedial action)
That last bit is also important. If you are breaking one of the rules, you should be explicit about it.
Write down the reasons in an obvious, visible place. A “Warnings” section in your module’s README / docs, for example.
When appropiate, you might want to add a small comment on the source code, too:
mymodule.trigonometricFoo = function(bar) -- Localizations make performance test #3 40% faster local sin,cos = math.sin, math.cos local baz = mymodule.trigonometricBaz ... end
Rule #6 turned out to be the smallest of the rules. It’s also very powerful. Remember what uncle Ben said about power.
If you need to break one of the rules and want to talk about your reasons, feel free to contact me; either post a comment on the rule in question or tweet at me.
Thanks for reading!