I’ve been thinking about this a lot lately, as I’m getting closer to a Genie v1.0 release and I want to finalize and stabilize the API. And I have a big big big problem with the recommended guidelines for naming functions. Namely, it involves a large amount of subjectivity - and this doesn’t work well in practice.
functions are lowercase (
convert) and, when readable, with multiple words squashed together (
haskey). When necessary, use underscores as word separators. Underscores are also used to indicate a combination of concepts (
remotecall_fetch) as a more efficient implementation of
fetch(remotecall(...))) or as modifiers.
If a function name requires multiple words, consider whether it might represent more than one concept and might be better split into pieces.
Words like “when readable”, “when necessary”, “combination of concepts”, “consider whether”, “it might represent”, “might be better” are riddled with subjectivity and ambiguity. They will inevitably lead to different expectations between package authors and package users, and between beginners and seniors.
I can tell you from personal experience of over a decade of programming in PHP, that mixing squashedcase with snake_case is one of the biggest problems for beginners. They lead to wasted time and energy and introduce countless bugs. These beginners might be your teammates soon. It’s for this reason that the various successful PHP frameworks introduced well-designed style guides.
It’s also for this reason that in many professional work environments, style guides are designed, adopted and enforced. Enforcing is done through a style checker which is part of the CI stack and basically every language has at least a few good ones. Which brings me to my point: Julia’s lax naming convention can’t be automatically enforced. If one wants to design clear rules, you’d have to go either with squashedcase, or snake_case.
And although I honestly do like the simplicity of
isdir, etc the problem with these is that they don’t scale. I actually happily started to move the Genie API to squashedcase and I was very happy with
newapp and even
newmodel – but I was horrified by the idea of
longfunctionnames would be a cognitive nightmare - but it’s not even a problem of length. Names like
readfile are OK while
readdir not so much because
dd (if you don’t agree you’re actually enforcing my point that this is 100% subjective).
We could come up with extra rules but they would be either too complicated for humans and/or checkers. For example:
- if name longer than 10 letters, use snake_case. Easy for the style checker to enforce, a nightmare for humans.
- if two joined words lead to same letter doubled, use snake_case. Easy for humans, difficult for style checkers (ie:
islessthanwhich would require a dictionary to understand the squashed words).
I am reluctant to make a recommendation in order to avoid the classic pitfall of the code styles flame wars. But it seems to me that the only style that works in any situation is snake_case. I also see this style widely used by package authors.