landline/HACKING.md

26 lines
1.3 KiB
Markdown

# 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.