Re: Syntactic Diabetes (was Re: A friendlier API for operating-system declarations)

[Attila Lendvai <attila@lendvai.name>]

> > the downside of generating countless macros is that they won't show up
> > in backtraces, and they cannot be found when grep'ping the codebase,
> > and as such make the codebase much less approachable.
> 
> 
> Reading your words really helped me feel that I'm not alone. You more or
> less summarized my feelings about the Guix codebase, which I have been
> reading now for over a year. Guile's syntax features make the code more
> symbolic and less approachable to newcomers.


just FTR, i don't think that the guix codebase is too bad in this regard.

here i just wanted to remind people to the not so obvious cost of syntactic abstractions that should be accounted for when making decisions. introducing macros that generate macros is rarely justified.

in general, it's *very* valuable when stuff can be grep'ped -- and not only for newcomers. after enough time has passed i can feel like a newcomer to my own codebase... :) modulo the protocols that i keep while writing code.

e.g. define.*whatever is a grep that i regularly employ. the pattern here is that although there are countless ways to define countless different stuff, there's a convention to stick to the define.*[name] pattern.

intuitive, unique (i.e. grep'pable) names are also key to facilitate code approachability, especially for abstractions that are scattered around in many source files. in some situations i even copy-paste names of abstractions into comments for any future grep'ping to pick it up.

a negative example for this in the guix codebase is the use of 'service' to describe two rather different abstractions: a component of an OS vs. a deamon process run by shepherd. for a while it caused me quite some confusion.

</rant>

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“The State is that organization in society which attempts to maintain a monopoly of the use of force and violence in a given territorial area; in particular, it is the only organization in society that obtains its revenue not by voluntary contribution or payment for services rendered but by coercion.”
	— Murray N. Rothbard (1926–1995), 'Anatomy of the State' (1974)