[craftedv2beta] Standardized way for naming functions
jvdydev opened this issue · 5 comments
I don't know if we have a standardized way for naming functions, if we do, we probably should document it.
;;; Version with '/'
;; Signature
(crafted-[module]/[function-name] ...)
;; Example
(defun crafted-defaults/some-special-function (...)
...)
;;; Version with '-'
;; Signature
(crafted-[module]-[function-name] ...)
;; Example
(defun crafted-defaults-some-special-function (...)
...)I think putting in the module name is important as it automatically documents where it comes from.
As for the separation character, I'm open for both (/ or -).
The / makes it look a little more special (compared to e.g. built-in functions), but my understanding is that the / is usually used for personal functions, not libraries (or by extension something like Crafted Emacs).
Also the - may be nicer to look at with interactive, but that's just my point of view.
We could split it between interactive/configuration functions and e.g. hook functions, but I feel that may add additional mental overhead without much benefit.
I was always working on the assumption that crafted-[module]-[function-name] is the established way.
If it's up for discussion, I prefer that over the / alternative. I haven't read tons of Emacs Lisp code, but from what I've seen I also gathered that - like @jvdydev mentioned - / is to designate personal namespaces while libraries, packages etc. use -.
ye, I had a similar assumption, however I noticed we don't have a clear guideline.
Since we want to move towards more automated testing and linting in the future, I think having the guidelines introduced beforehand is good so it's not as drastic of a change.
It also helps new people find their grip in the project easier.
Same naming would apply for variables/defcustoms (although those should get rare, but having a good guideline on naming them won't hurt).
Just wanted a small discussion place instead of just changing the guidelines docs 😄
I also totally forgot we link to the Emacs Lisp Style Guide in the README.
Probably should mid-to-long-term introduce a contributing section in the info file for contributing code (the "CONTRIBUTING.org" file is only on docs currently, probably merge code stuff in there too).
Might be useful for people who are comfortable in Emacs, but may not be comfortable with git/GitHub and how to contribute things.
Just some thoughts, once I have some more concrete ideas on how that would look, I'll PR them.
More thoughts, opinions and suggestions welcome 😄
I'm not as big a fan of the / separator between the "namespace" and the function name. It's just harder for me to type quickly, which is usually mitigated by a completion UI, but still...
Generally, I agree we should follow a consistent naming structure, for me that would be module-function or module-variable, thus crafted-defaults-do-a-thing for a function or crafted-defaults-thing for a variable. I believe that is inline with the style guide we link to anyway, so sticking with that makes sense to me at least.
We might consider adding a CONTRIBUTING.org to the modules section to describe how to contribute code as a deliverable for RC1... thoughts?