Naming style guidelines

• As functions are a process, action - therefore the main word in function names is a verb. The most useful writing advice (for literature writers) - is to use verbs instead of auxiliary words ("very") or adjectives. A good thing to look at.

  • Builders are functions - they start with mk.

  • Unnamed local functions are fun.

  • Unnamed recursive local functions are go. If the function does not have recursion - please, do not name it go name. & recursion is always a special thing important to know about.

    For counterexample - adi is a bad name for a function, acronyms generally are, especially if consider no sufficient explanation is given for it, adi is for Abstract Definitional Interpreters - which is just great ... It still does not say much but at least some direction to several Computer Science papers to read. In reality, all it does & is for is to interleave actions or data layers in data type, embellish, addsMetaInformation/Annotation to something. But general adi is interleave.

  • Please, use {fold,sequence,traverse,show,put,map,bind} & other verbs of famous type classes inside the function names with that main assence.

  • Since HNix is also a library, functions that are generalized/customizable/transformation-able versions of a default implementation function & ends with an F, as having a higher-order functor nature added to the main implementation. Examples would be MonadThunk{,F} type classes with functions accordingly named ending in {,F}, as F functions take in a Kleisli arrow they pass around.

  • Instead of F names can have A for applicative and M for monad - if they indeed have Applicative of Monad nature of computation, but since applicatives & monads are functors (in terms of theory - applicative functor and every functor is a monad, every monad is a functor), F is recommended default choice.

    Quite frequently the code implementation is too generalized (for example the Value module methods) for "project as a library" purposes, while for "project as an implementation" purposes the default implementation are created, in that case, the generalized versions become renamed to have F.

• Main word in an object (variable/data type (kind *)) - is (mainly) a noun.

  • Data & type constructors are considered variables - they are nouns (or adjectives).
  • Data record:
    • Start with a get.
    • newtypes go without record & use Haskell Core's coerce with adding type-level signatures (documentation) to local functions. If newtype is too hard for GHC to infer coerce in polymorphism - only then add a record unTypeName to use it.

• Starting anything with _ reserved to named bottom/typed holes. GHC & HLS specifically support this way. Those provide code readability, for example otherwise says nothing, _NixStringOrStringLike - is descriptive, so when bottom trap bug is found - contributor can tell for what case that bottom was created for. They also give a hint at the functionality to implement, or functionality/argument that can be reduced.

In other cases https://kowainik.github.io/posts/naming-conventions is recommended.