Rule #6: Break the rules

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

Good reasons are based on objective, testable or measurable evidence - and on occasion they are accompanied by palliative actions.

Bad reasons

Bad reasons, on the other hand, are subjective, based in the unknowns, or just plain lazy. They take no remedial actions:

Say it

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

Conclusion

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!