landline/HACKING.md

Notes and things to consider on Landline hacking

The structure of the Landline rewrite was specifically redesigned to allow for extensive modification and extension. So to keep things that way, you may want to consider the methodology of writing Landline code.

Recommendations

To keep things beautiful, consider following recommendations:

• USE COMMON SENSE. None of these guidelines will ever be adequate enough to replace common sense.
• Code less, think with portals what you have. To minimize code overhead, try to use existing functionality to get the effect you want. (i.e. if you want to append headers to a request when it traverses a path, don't write a new class variable and handler for this - just create a new DSL method that really just appends a preprocessor to the path. Or avoid making something like this at all - after all, preprocessors exist exactly for that reason.)
• Preferably, *extend the DSL and not the class. Extensive class modifications make code a lot less maintainable, if it wasn't obvious already. If it can't be helped, then at the very least use Rubocop.
• Document classes as if the next maintainer after you has you at gunpoint. Document thoroughly, use YARD tags and never skip on public method docs and class docs. As an example, consider Landline::PatternMatching::Glob.