Kadena Lens Guidelines

LensGuidelines.md

Lens Usage Guidelines for Kadena Code

The purpose of this is to enforce regularity around usage of the lens library. Lens gets a decent amount of flak for (a) horrific type errors (not much we can do with that) and (b) illegible squigglies. My issue with the squigglies is they cause OO- (or OCAML?)-style left-to-right evaluation. Thus, I'm not offended by some of the state-monad operators, as they slot into where <- would go in do notation.

But in the end, the ones I object to are really because their wordy counterparts are reasonably short. The big advantage of the squigglies in the end is not having to put parens around lens compositions, but to my eye that's trading off legibility.

The General Principle: If It Flips App Order, Don't

I'll go ahead and be explicit below but want to say it in general: resist the urge to & up your code. This avoids all of the operators listed, plus their C-like brethren like ^^~, which of course you know what that one does right? Just by looking at it. Not ...

Instead of	Use
^.	view
.~	set
%~	over
^?	firstOf
^..	toListOf
^?!	No equivalent thank god do not use ever!! MY EYES

Good Stuff

As good as these are I find many people don't even know there are non-infix versions, so this is a reference of those.

Useful squiggly	Literate equivalent	Justification
.=	assign	Best in State* monad code.
%=	modifying	Best in State* monad code.
?~	set + Just	With tons of Maybes then this could maybe make your code nicer ;P
?=	assign + Just	Best in State* monad code.

General Escape Hatch

If for some reason an individual module is so ridiculously lensy that it's just the only way to go, or you're interacting with some idiomatic code (as might be the case with Reflex), then it can be justified.