Hey, help me out... I want the Golem demo to be as understandable as possible. I know, I haven't written all the docs yet, but what's easier for you to read:

- All in one file, like this:
- Split into multiple files:

Pls let me know! Your feedback appreciated!

One file: +++
One file but if it gets too big multiple files: ++
Multiple files: ++

And yes, adding a README/documentation, ack :)

whether or not to split seems split, but I did know I was asking friends to help me paint this

@cwebber All in one file is easier to read as long as its not too long, but I prefer when it's split into multiple files. However, in the latter case, you could use conventions of racket packages so that the entry point is easier to recognize.

I tend to like 1 large file best. Especially if the sections are separated with headings.
@cwebber Thus far, it is less than 500 lines, so a single file is still acceptable. Much bigger and it becomes much harder to keep things in mind. You have a nice small number of separated files, which is easily managed and helps with comprehension. I think it is easier to understand that way.

CC: @storm
@cwebber If I was unclear, I was saying that the multi-file version is easier to understand, and that the larger it gets, the more the advantage goes to the multi-file version.

@cwebber Single file is easier to scan through, if kept small.

Having said that, I'd assume that people will use the demos as boilerplate for starting their own projects, so I'd organize it however I think the project should be structured. If that is multiple files, then I'd include a README with notes about what is where.

@cwebber What about a README where each chapter/section is also a separate file that just is included in the main file?

@FiXato are you asking for literate programming? because it sounds like you're asking for literate programming ;)

I usually prefer the one file approach because it's easy to scan through. A multiple file approach requires a tutorial in which you can have the reader create files on the go, otherwise you don't really know where to start, in which order to read them, and why they're here. Anyway your project looks really cool, I'm glad someone is picking up #Racket to make such an ambitious project. Good luck!

@cwebber yeah why not docs first implementation 2.?
Also if they are so small they should be easy to implement in different languages? I think a lot, like a lot of people don't have the mindset of functional programing only. That's why having js or python (plz!! Python 😊) or any other c style implementation as well would help many people.

Sign in to participate in the conversation

Octodon is a nice general purpose instance. more