Clojurians Log v2

I have submitted a couple of PRs - if you are in a reviewing mood, feedback is MOST welcome.

https://github.com/cljdoc/cljdoc/pull/331

https://github.com/cljdoc/cljdoc/pull/334

I did not fix the problem, but I did correct the spello :simple_smile: https://github.com/cljdoc/cljdoc/commit/d54cb58b20d2b4cb1e7c714b3637aa8b89956ce0

I am starting a clj-kondo lint pass on cljdoc source. Fun fun fun!

clj-kondo warns about unused things, and I see quite often destructuring of keys that are not used, for example group-id and artifact-id are not used here: https://github.com/cljdoc/cljdoc/blob/d54cb58b20d2b4cb1e7c714b3637aa8b89956ce0/src/cljdoc/server/ingest.clj#L16

before I delete, was this some sort of strategy to help when walking through code with debugger or something? @martinklepsch

I recently commented on this here: https://github.com/candid82/joker/issues/240#issuecomment-508985091

Thanks @borkdude, so it can be used to document the the incoming data structure… hmm…

at the cost of unnecessary destructuring.

you can also write (s/fdef ...) since there are already specs in cljdoc, it seems

and maybe confusion? Without clj-kondo I was assuming all destructured keys were used.

right. I'm leaning more towards 'only destructure what you need' these days

I think I am too. Like you say, if it needs more describing there are specs - although they can be far away from the function you are reading.

you can also put the expected keys in the docstring

but since there is a spec assert there anyway, you'll discover this soon enough

I thought this project announced today looked interesting: https://github.com/nedap/speced.def

anyway I shall wait for @martinklepsch to opine for cljdoc.

Yeah I suppose if they aren’t used they are really a comment, so docstring would be an alternative.

Anyway lots of fun to see what clj-kondo finds @borkdude!

I agree, it is fun 😉

actually @borkdude if the intent is documentation, although an underscore prefix might seem silly on a destructured key, it does convey the key is available but unused.

(ignoring performance cost)

but then you would be destructuring keys that aren't even there

ya but you aren’t using them anyway

so what’s the diff?

right

unless intent is also to see them when walking though with debugger…

some editors give you the arg names and destructuring info as you type. when you see underscores keys that's possibly confusing

when debugging things, you can destructure when you capture that map

ya… I don’t think intent is debugger support, just making wild guesses.

the convention of underscore = unused is wildly understood, I think people would understand… oh but editors might give confusing help… I see.

it's an interesting topic for cljdoc: destructuring as documentation, yes or no. I guess you will also see it in generated documentation?

i think so, lemme check…

yup: https://cljdoc.org/d/cljdoc/cljdoc/0.0.1315-c9e9a7e/api/cljdoc.server.ingest#ingest-cljdoc-edn

so then the question is: is there a way to get this information without paying the penalty of destructuring? e.g providing an arg-list, or spec

or docstring

user=> (def ^{:arglists '([{:keys [:x :y :z]}])} f (fn [obj]))
#'user/f
user=> (doc f)
-------------------------
user/f
([{:keys [:x :y :z]}])
nil

codox might also pick up on that

cljdoc also looks at the arglists metadata

(And the code is largely based on codox)

I think specs would be a more complete/interesting data source than the destructuring and explicit declaration we can find in arglists metadata

Spec stuff really needs to be revisited. At some point I threw in the towel but maybe a different pair of eyes has different ideas

If there’s interest I would be happy to summarize my findings and some stuff that’s spread across GitHub comments

I added arglists to this discussion: https://github.com/candid82/joker/issues/240#issuecomment-515616779

@martinklepsch I started asking about this when looking specifically at cljdoc codebase… then we got into our interesting general discussion. For cljdoc codebase, am I right that, for now, unused destructured keys act as documentation and should be left in?

(or move them to arglists if they aren't used, but you still want them in the outputted docs)

(right, good alternate option)

@lee I have explored using them this way but haven’t come to a strong opinion on either choice. Without an explicit decision (ADR) I’d suggest to not touch code solely for formatting* sake but if we need to make that decision we can totally just reformat everything 😂 *thats kind of how I view it I guess.

yeah for this topic, that makes sense to me.

unused namespaces are easy… they get deleted from code. unused destructured keys are a topic of their own.

If a linter doesn’t like this ~formatting that might be enough of a reason to make a change

well, the linter is just asking, “hey, are you sure you want to do this?” and we can answer, if we want, “thanks for the tip, we like things this way”

right now our answer for unused destructured keys is: we’re not sure, so thanks for the tip, but we’ll stick with what we are doing for now.

(I think)

or… we could try out @borkdude’s arglists metadata idea.

@martinklepsch, on the topic of formatting, I often forget to leave a space here or there in a commit, have you considered using a format checker to check for this type of thing? maybe cljfmt would work for this?

oh it is getting late for you guys… let’s chat another time.

it's finally cooling down here. we had a couple of days of 37-40 degrees Celsius and at night it wouldn't cool down below 24...

so I'm going to catch up some zzzs now

g’night

Good evening Lee! 👋