TLDR: I am struggling to best organize a bigger package specifically in elisp, due to everything being global/unscoped in elisp. Instead of e.g. Org8/AgentSession/Backend/ClaudeCodeVterm.hs with sessionTranscriptTailMesssagesCache function in it, I end up with org8-agent-session-backend-claude-code-vterm.el with defun org8-agent-session-backend-claude-code-vterm-session-transcript-tail-messages-cache. I have 20+y SWE experience and am not vibing it, I just love organizing code well.
Hey all, I am writing a somewhat bigger emacs package for some time now and I am starting to really struggle with long names of my functions/variables/files, and while I am quite sure at this point there is no great solution, I am hoping somebody might point me to a solution that works well enough in practice.
Btw my main languages are Haskell and TypeScript, so I might below accidentally use some terminology from there.
Ok so since in elisp everything is global, I prefix all symbols with <pkgname>-, ok that makes sense. In my personal config I was always using my/.
However, I have quite a few of files/modules in my package at this point, and I wanted to prefix functions in a way that makes it clear which module they come from. So i started doing <pkgname>-<module-name>- as prefix for symbols.
However, some modules are conceptually submodules of other modules, so that <module-name> in some instances is getting really big, because it is really <parent-module-name>-<child-module-name>, and that might even go to the third level.
And that sucks because of length, but I would say even length is not the biggest problem, the biggest problem is that once this whole big prefix is done, comes the name of the acual symbol, wihch is also likely multiple words, and there is no clear way to differentiate where the prefix starts and symbol beggins.
One of more extreme examples from my codebase, to show how ridiculous this gets:
org8-agent-session-backend-claude-code-vterm-session-transcript-tail-messages-cache
where org8-agent-session-backend-claude-code-vterm is prefix and -session-transcript-tail-messages-cache is what really carries the info on what symbol is in this context.
If this was some other language, I would have dir structure like Org8/AgentSession/Backend/ClaudeCodeVterm.hs and in it function sessionTranscriptTailMesssagesCache.
I guess I am addressing multiple problems here:
- Names are too long.
- There is no clear delineatinon between parts of the name.
I considered using some kind of abbreviations for names, like org8-as-b-ccvterm, but that is so hard to guess what it means.
I considered organizing it all somehow into directories but from what I understood so far that is not really how it is done for packages because it complicates distributing them, instead all is kept on top level.
I considered dropping part of prefix, just doing org8-claude-code-vterm, but I really don't like that when I konw where it belongs and this obscures, when looking at it in e.g. dired, where it fits into the whole codebase.
I am currently playing with shorthands, using this/ and this// to shorten prefix for public and private symbols, but that works only inside that file, make it much harder to search for a symbol accross files, and also doesn't solve long names for symbols I imported. Also, public symbols still look ridiculously long to users of the package.
Above is mostly about shortening the names. As for delineating prefix from actual name, I considered using /, like org8/agent-session/backend/claude-code-vterm/session-transcript-tail-messages-cache, but that is not a convention and I am worried it will look real weird for users when using the package public functoins, nobody does that from what I saw.
Thanks for any advice, I feel like while in theory these are just shortcomings of elisp, there must be some practically blessed way that works well for people so would love to hear what works, and that might also help me accept it.
EDIT: Seems that some commenters wonder if I am just overengineering or vibing this and it's a ton of slop code, so just want to clarify upfront that I am not, this is a bigger package at this point, been working on it for months, and it is somewhat complex, multiple subsystems, backends, implementations of those backends. I stick to my own versoin of Clean Code so I keep functoins small, I keep modules organized by responsibility, I use descriptive names, and so on. I have been programming like this for 20 or so years and enjoyed it so far, just have never done it in a language like elisp that has no scoping. And I am not complainng about elisp, I get that it is older and has its quirks, but am looking for practical advice how to get the most out of it.