Sanctuary: Structuring in different directories and files

[fnune]

My question may be naive, considering I don't know about any decisions taken regarding code structure, but is there any reason to have all the code in index.js apart from avoiding a build system (which would admittedly usually a pain)?

Separating the code in directories and files for each feature could make it easier for potential contributors to make their changes and for library users to find the piece of source they want to read.

[davidchambers]

Avoiding a build step is a huge win as far as I'm concerned.

There are other reasons I prefer having a single source file rather than one file per function:

• It is ordered. The documentation is ordered, so we need to specify order somewhere. Were we to switch to an inherently unordered project structure we would need to maintain an ordered list of file names or function names. By declaring the functions themselves in order we avoid the need to create and maintain such a data structure.

• Generating the readme from the source code (via Transcribe) is simpler with just one input file.

• Testing code examples in the documentation (via doctest) is simpler with just one source file.

• Code reuse comes at no cost. There's no need to import a function in order to use it in the definition of another function.

• Having the code in a single file makes grep/ack/ag/rg serve as a documentation viewer. Run grep '//#' index.js to see what I mean. ;)

Separating the code in directories and files for each feature could make it easier for potential contributors to make their changes[.]

Could you elaborate on this?

Separating the code in directories and files for each feature could make it easier […] for library users to find the piece of source they want to read.

Perhaps so. I've actually spent time and effort on this problem, and I believe the current approach to be quite good, but I may not have done a good job of drawing attention to it.

The function name in the header of each section of the documentation (both on the website and in the readme) is a permalink to the section of code exactly as it existed at the time of the release in question (likely the most recent release). This means one can find the source code for S.get, for example, by visiting https://sanctuary.js.org/#get and clicking on the function name. Alternatively, one can search for # get :: within __index.js__ to jump to the definition (I find this very helpful when navigating the file in Vim).

If you're considering contributing to Sanctuary (wonderful!) but find the large file daunting, what specifically is off-putting? Are you thinking of adding a function but you're unsure where it should live? Is it breaking syntax highlighting in your text editor? I'm happy to discuss any such concerns.

I'll reconsider splitting the source file if and when someone convinces me that "tree shaking" works in practice. :)

[fnune]

Thanks for the detailed answer! It's awesome when library maintainers are responsive :)

Could you elaborate on this?

Personally, the first thing I do when reading a library's source code is to skim through the different sections and folders to try and get an image of what each part does and why it's organized the way it is. I suppose the use case for Sanctuary would be different, because its functions are all "on the same level", i.e. the file structure would be flat, like Ramda's.

Finding a single file gave me unfounded doubts about code quality (I repeat, unfounded). I myself have a little JavaScript module written in one file (_and_ with a build step) which I'm deeply ashamed of and am planning to refactor. You do have good reasons to keep source in one file: why don't you comment about it in the README? That very explanation you gave me seems to be appropriate for documentation, especially useful/clarifying for newcomers.

I'm currently learning about functional programming in general so any related libraries are interesting. I admire the knowledge of people maintaining them. When I've studied a bit more about it I'll consider contributing. With your explanation, the single source file is by no means off-putting.

Again, thanks for the answer and congratulations on the project!

[davidchambers]

Personally, the first thing I do when reading a library's source code is to skim through the different sections and folders to try and get an image of what each part does and why it's organized the way it is.

Ah, yes. Now that you mention it I realize I do the same. :)

Finding a single file gave me unfounded doubts about code quality (I repeat, unfounded).

This thought had not occurred to me, but I do understand it. I once joined a team which had a single 5000-line JavaScript file for all the client-side logic! There does tend to be a correlation between small modules and modular, well-factored code. As you may have noticed, Sanctuary is modular and well factored despite its monolithic appearance.

That very explanation you gave me seems to be appropriate for documentation, especially useful/clarifying for newcomers.

Good idea. We could add an FAQ section and link to this issue.

I'll close this issue, but you and others should feel free to post additional comments.