4

Some Lisp programmers advocate keeping code mainly into one file, following the concepts of Literate Programming in the Large, (note: the video is more about the method than Axiom, an open source computer algebra system written mostly in Lisp).

There is also a tendency to split a long elisp file into related files.

Some believe this may be a matter of personal opinion. Doing some research, it seems, at least in Lisp, such issue is also a matter of proper coding style and proper code management.

Quite a few experienced Lisp programmers spent considerable time about this subject. There are whole books and online documents that speaks about style (for example, Molly Miller's "LISP: Style and Design").

I was wondering what approach in managing code is advisable when dealing with large elisp (and lisp) files?

Based on on that, which special tools (ie, unique to elisp programming) does Emacs offer to navigate either a long elisp file, or a collection of related lisp files?

I am especially interested in less widely know tools. For example, there is code out there to help unbinding things or nuke and reevaluate an elisp buffer. It seems that kind of tools could be quite useful, but they would probably not make much sense for very large files?

Bonus question: Is there a criteria, like grouping into logical units, or other quantifiable values (like: LOC, number of functions, etc) that can help in deciding?

gsl
  • 1,742
  • 17
  • 34
  • 3
    I don't think there are hard criteria. Ultimately it's just a matter of taste. –  Jul 26 '15 at 18:00
  • 2
    *I really need to have a clear idea of what is the better system.* I don't think you will get there with a question like this on StackExchange. As currently posed, this one should probably be closed as *primarily opinion-based*. You might try asking such a question on a discussion forum. Consider using `help-gnu-emacs@gnu.org` or another venu, or try to come up with a less opinion-oriented question for here. – Drew Jul 26 '15 at 18:30
  • 1
    "arguably" is the word! Maybe this question would be better off on programmers.sx? Or even productivity.sx (what makes the question specific to code files, instead of any document?) – T. Verron Jul 30 '15 at 10:03

1 Answers1

8

There are various coding standards which enforce certain maximal length. One popular example would be to say that a function shouldn't span more than one screen. Obviously, there are different screens (we aren't talking about terminals from the middle of the previous century), but the rationale here is also obvious: scrolling doesn't aid reading.

But I'd stop much sooner. According to various researches, we are able to hold somewhere between 4 and 7 things in our immediate memory at once. This would make an ideal paragraph of text have four to seven sentences. Similarly, an ideal function would have four to seven statements in it, so that when reading it, you wouldn't need to re-read just to recall what other "stuff" there was. This value also varies with experience you have with reading code, similarly to how when children learn to read, they distinguish smaller chunks of text (syllables, or even single characters), but need special effort to distinguish larger features, programmers, who read more code can parse the structure easier.

Another metric is to ask yourself whether the purpose of the function is properly defined. Isn't this function doing more than one thing? Try to imagine scenarios, where a part of the function may be used alone, without having to use the remaining part. If such a scenario is easy to imagine, it's time to split the function in two.

Obviously, none of this gives a numeric estimate, yet it certainly may be used against your opponents at code review time ;)

wvxvw
  • 11,222
  • 2
  • 30
  • 55
  • 1
    I would say that, personally, 4 to 7 is a bit small. Of course, smaller functions mean more jumping/more context switching and I'd rather take the code in larger chinks. I don't really know where my personal perfect length is, but I can definitely say that some of the 100+ line functions in the Emacs source are absolutely killer to parse. I would implore you to _never_ write anything like that. – PythonNut Jul 26 '15 at 21:57
  • 1
    @PythonNut it took me a while to find this: https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two - and, well, it's just what psychologists believe the number to be. I didn't count it myself :) – wvxvw Jul 26 '15 at 22:27
  • Thank you, it makes lot of sense. One thing related to elisp code I found is that one can compile a buffer at once. It is convenient to be able to load only a certain logical group of code and compile it as separate entity. I am sure Emacs and elisp offer other reasons to split a large file into logical chunks. – gsl Jul 27 '15 at 04:39
  • re 7+-2: "But the point was that 7 was a limit for the discrimination of unidimensional stimuli (pitches, loudness, brightness, etc.) and also a limit for immediate recall, neither of which has anything to do with a person's capacity to comprehend printed text." - http://members.shaw.ca/philip.sharman/miller.txt – npostavs Jul 30 '15 at 09:21
  • @npostavs this is very interesting, and I didn't know about it. Nevertheless, I wouldn't discard this claim so quickly. My mother is a practising psychologist with more than 30 years of practice. She specializes in tests required for carrying weapons and similar activities which must ensure the person is "sane", i.e. she works with mostly "healthy" individuals. One step in the examination requires reading ten nouns or adjectives and reproducing the list. Most people fail to do this until the same experiment is repeated three times, - this is normal. – wvxvw Jul 30 '15 at 09:53
  • 1
    Most people will also reproduce around 6 or 7 words from the list at first try. My non-professional conclusion from this experiment is that if you can think about a function as a number of atomic blocks-statements, then in order to picture it in your mind's eye, on first reading, it would be a lot more convenient if you could remember all the parts at once. Of course I'm aware of complexities of understanding printed text and would never suggest this to be a rule, but a useful heuristics. – wvxvw Jul 30 '15 at 09:56