Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add FAQ or guide for example projects #586

Open
puredanger opened this issue Apr 11, 2022 · 6 comments
Open

Add FAQ or guide for example projects #586

puredanger opened this issue Apr 11, 2022 · 6 comments

Comments

@puredanger
Copy link
Member

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
Copy link
Contributor

PEZ commented Apr 11, 2022

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
Copy link
Member Author

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
Copy link
Contributor

plexus commented Apr 13, 2022

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/land-of-regal is the source of https://lambdaisland.github.io/land-of-regal/

@adityaathalye
Copy link
Contributor

adityaathalye commented Apr 19, 2022

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
Copy link
Contributor

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

@tfidfwastaken
Copy link
Contributor

"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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

6 participants