Fork me on GitHub
#beginners
<
2018-06-13
>
torvaney09:06:17

Hi all. Potentially a strange questions here. I often find myself defining a function that looks like this:

(defn map-vals
  "Apply a function to values in a map."
  [f m]
  (into {} (for [[k v] m] [k (f v)])))
It seems odd to me that I should be doing this frequently, without an option in the standard library somewhere. So then my questions become: • Is there an easier/more idiomatic/better way to do this? • Is this a sign that I'm doing something else wrong/weirdly/unidiomatically? For instance should I be storing data differently?

petterik09:06:44

mapping values in a map is something I do frequently as well. I usually use the map-vals implementation from medley.core (https://github.com/weavejester/medley).

torvaney13:06:03

Thank you @. That's really helpful

seancorfield15:06:22

@torvaney https://gist.github.com/seancorfield/6e8dd10799e9cc7527da5510c739e52f (if you're using clj and want to "depend on" a Gist)

seancorfield16:06:13

I was amazed when I first saw it done -- mainly because I didn't know Gists could be multiple files.

torvaney08:06:39

As far as I understand it, a gist is essentially just a git repo (there are some cool tools like https://github.com/mbostock/gistup for working with them), so anything you can do with a git repo, you can do with a gist. That said, it would never have occurred to me to do this!

lady3janepl21:06:49

Is there a good style guide for docstrings?

alexmiller21:06:41

all emoji, all the time

lady3janepl21:06:32

Next time I need to add a warning, I will:

lady3janepl21:06:33

:exploding_head: 😱 🙈

lady3janepl21:06:52

…also, yay, repl prints out docs with emoji in them XD

lady3janepl21:06:49

we have this miraculously powerful technology and this is what we use it for 😄

alexmiller21:06:49

tbh, no one reads the docs anyways, so emojis might help

lady3janepl21:06:21

this guy I worked with couple of years back had an amazing idea

lady3janepl21:06:39

he wrote a choose-your-own-adventure in class level docs

lady3janepl21:06:01

If you turn left, see class X. If you fight the monster, see class Y.

lady3janepl21:06:27

You know you’re a hardcore player if… you read through all the class docs to find the secret location you can’t get from anywhere in the graph 😄

dpsutton21:06:39

to the actual section

dpsutton21:06:21

sorry i was going there at the same time 🙂

lady3janepl21:06:03

Yeah, I’ve seen this one; then I got confused by a discussion of how to mark arguments

lady3janepl21:06:52

Did backticks win as the preferred method of interacting with tooling?

lady3janepl21:06:40

if you actually call (doc ...) on that, repl prints them out:

Returns a new map with value `v` stored under lookup key `k`.

dpsutton21:06:26

so those are competing "standards". The CIDER version never materialized so ignore that. Codox is a thing but it depends if are planning to use it. I wouldn't worry about it if you are asking in #beginners. There have been proposals to make the docstrings more structured like in emacs lisp. That uses capital letters for variables and some other conventions which tooling can assume. Those conventions are nowhere in Clojure so their adoption is most likely not to happen

lady3janepl21:06:41

Nah, it’s not even a library for other people’s use. I’m trying to pick up good habits / not pick up bad ones 🙂

dpsutton21:06:02

asking questions like that is a good habit 🙂 just pay attention to which doc strings are helpful to you

lady3janepl21:06:38

codox looks useful, thanks! I like the ability to use markdown

lady3janepl21:06:38

(I work in a dynamic language that went from “…you can add comments, whatever” through “…and here’s a tool to generate HTML docs if you use this comment format” up to “…also here’s a static analysis tool that pulls type hints from docs”, so I’m house trained to pay attention to comment format 🙂)

seancorfield22:06:46

FWIW, with docstrings, I tend to favor the following general structure: "Given a thing, another thing, and something else, return some computed value. Elaborate on conditions for what might be returned."

seancorfield22:06:22

"Given a rule specification in English, return the parsed rule
  or a string containing an error to be reported back to the user."
for example...