Add FAQ or guide for example projects

[puredanger]

One of the most common requests we see from Clojure learners is for example real code bases to look at that demonstrate good style and usage. There are many good answers to this question (you can search Slack or other sources to find places people have answered this, often repeatedly). I would like to have a well-known place that we can point people to when they ask this question (and/or point them to it proactively in our getting started path).

This could just be a https://clojure.org/guides/faq entry with a guided list of suggestions or a whole new guide that provided more context.

[PEZ]

Is it only good stule and usage you are after here, @puredanger, or would it also fit with template-ish projects? For instance, I get good feedback from users starting their ClojureScript + React Native journey using this example/starting project: https://github.com/PEZ/rn-rf-shadow I doubt it is very useful for learning style.

Mainly trying to understand what kind of resource you want to create here.

[puredanger]

Interested in both. I think people ask this question both for "what's something similar I can copy and hack on" and also "what does a real project look like". I'd be happy to munge those into the same faq answer/guide until it becomes clear they are two different things though.

https://github.com/seancorfield/usermanager-example is another good example.

[plexus]

Looking at what we have to offer I think such a guide should be organized by use case/stack. "Traditional" http/html backend, CLI app, React-based frontend, etc.

---

Some submissions we can offer:

The Clojurians-log-app was created with this purpose in mind, have a fully fledged app that people can hack on and learn from. That said there are a few things in there that are a little atypical. https://github.com/clojureverse/clojurians-log-app

There are also several mini apps I've created for specific Lambda Island episodes

• https://github.com/lambdaisland/booklog
• https://github.com/lambdaisland/rolodex-gui
• https://github.com/lambdaisland/breakout
• https://github.com/lambdaisland/redolist
• https://github.com/lambdaisland/compobook
• https://github.com/lambdaisland/react-calculator

https://github.com/lambdaisland/land-of-regal is the source of https://lambdaisland.github.io/land-of-regal/

[adityaathalye]

So i started writing an FAQ, but things got out of hand and became a (opinionated) blog post [1].

I've tried to articulate what I believe I’ve done subconsciously over the years.

• A quick motivating example
• Heuristics to choose a project to read
  • Choose an area of knowledge one is already comfortable with (web/HTML, web/HTTP, algorave, DBs etc.)
  • Cook up a decision-making matrix of #{libraries} X #{heuristics}, like so:

Heuristic / Library	Lib A	Lib B	Lib C
Code size (LoC)
Code complexity (high/mid/low)
Utility
Stability (high, mid, low)
Docs
Talks
Tutorials
...

• Effective way(s) to read a project
  • Read the README and API docs
  • Use the REPL
  • Learn to navigate the code
  • Experiment
  • “Comparitive Literature” approach
  • Write your own Alt-implementation
• Suggested projects with short reasons why to read
  • Some libs, and Applications of the "copy and hack" variety
• Thinking aloud about whether HOWTOREADMEs make sense in libraries

---

(Edit: updated comment with enough context so people don't have to go read the blog post.)

---

[1] Post: Which Clojure codebases should I read? How and why? 😁 [asciidoc version here, orgmode -> pandoc -> ascidoc]

Please pardon errors and omissions. I just banged it out and hit "ship", to try and participate in this conversation without hijacking it with a giant comment.

[ertugrulcetin]

Maybe for a 3D multiplayer game prototype, I can share my repo: https://github.com/ertugrulcetin/herfi
It includes: Clojure, ClojureScript, Three.js

[tfidfwastaken]

"what does a real project look like"

This addition to a central source would help a lot!

My perspective as someone who wanted to learn web programming fundamentals over the last three months via Clojure:

Reading the codebase of popular libraries (Ring/aero/clojure.core etc) was enlightening, but the highest return on investment for me was reading the code of web apps like nilenso/receive and other onboarding or downtime projects that my colleagues wrote at my organization (which have been deployed in the wild at some point).

I have felt that in Clojure-land, many popular libraries are quite minimally documented (many a time you only get a public API reference and nothing else). I found it helpful to see a web app that has been deployed at some point. With those examples, I can see how the authors actually used the libraries and dealt with the various edge cases and caveats of using them (An example I can think of atm is "how do people do structural validation of HTTP request form parameters? Do they use clojure.spec for this, and if yes, how?").

</ end of part about learning web programming>

Additionally while learning Clojure idioms itself, I found it valuable to look at core library functions, and compare it with some specific 4clojure problems that ask you to implement them.

It’d also be neat to have example repos that demonstrate some of these things (since I haven't run across any from my exploration):

• Demonstrates web applications with asynchronous handlers
• Interacts with popular production tools like queues, caches, gRPC-based services, live streaming etc.
• Demonstrates effective use of Java interop
• Demonstrates solid utilization of testing patterns: fixtures, property-based testing, and effective usage of spec

I also agree with @plexus about categorizing by use cases (with emphasis on production practices)—like I mentioned above, web applications that use popular Clojure libraries (of varying scope and sizes), and something that demonstrates Java Interop would have been a perfect resource while I was learning Clojure.