[DigitalJack]

I admit to still not understanding what goes on with function definitions in clojure, but this idea of just making a micro change in clojure and evaling that and seeing the real time effects never seems to pan out for me.

I do lots of small functions that build on each other. If I make a change to one of the base functions, the higher functions seem to hold a reference to the old definition and I end up having to re-eval everything or go figure out every place I used that function.

I'm sure there is a better way but I haven't found it yet. I've tried using some ideas from Stuart Sierra about reloading namespaces, but I spend more time trying to orient my code to work with their ideas than just getting something done.

And documentation in clojure code in general is very poor. People think their code is self documenting. It is not.

While clojure is wonderful to write in, it's not nearly as enjoyable to read. The more macros and syntactic sugar people add to their programs, the less likely someone is going to be able to read, understand, and use that code.

[astine]

If macros are used properly, they should make the code easier to read, not harder. If you can't figure out what it does from it's signature and docstring (maybe with a reference to some documentation for more complex or abstract things,) there's a problem. You shouldn't have to read a macro's definition to be able to use it.

Also, redefining a function should cause every function which directly references it to use the new version. You can sometimes run into issues if the functions are defined in separate namespaces or if the redefined function was passed to the other as a higher order function during the latter's definition.

If it's a macro you're redefining, yes you'll have to redefine functions which depend on it, but you should be defining too many macros.

[dllthomas]

"If macros are used properly, they should make the code easier to read, not harder."

Well, I think macros often play the role of jargon. They let you spell out a particular concept succinctly and precisely and make the whole much easier to follow once you are familiar with the jargon, but people unfamiliar won't fully understand.

Much like jargon in spoken language in any field it can be picked such that those otherwise familiar with the language draw conclusions (that are hopefully correct), or picked so that they recognize that they are unable to draw substantial conclusions (which may be incorrect). There are upsides and downsides to both approaches (which isn't to say one doesn't dominate, but from my limited perspective it's not clear).

I should note that, to some extent, this is true of most kinds of abstraction.

[astine]

I suppose. If you don't know what a for loop does you can't really be expected to use one. But you shouldn't have to understand how a for loop is implemented in order to use it correctly is really my point.

Macros can be used to implement some pretty novel abstractions so there can be some temptation to try to understand them by reading the implementation. However, if an abstraction is novel enough, it really should be documented somewhere very thoroughly.

So, to some degree your analogy makes sense. You can use macros (and functions too, really) to express concepts that are unclear unless you have a better familiarity with the topic or the program in question. But I feel that that's what docstrings are for.

[dllthomas]

All certainly the case. Any sort of jargon should be well defined and well documented. Standardizing on jargon between groups eases transitions between groups, but may mean it fits individual problem domains slightly less well. &c, &c.

[Morgawr]

>And documentation in clojure code in general is very poor. People think their code is self documenting. It is not.

Clojure functions and macros have docstrings you can query with the "doc" function. Honestly I've started keeping a repl open all time like I used to do in C with a terminal + man, so I can use (doc whatever) or (source whatever) to see the documentation + implementation details of most of the functions I use.

[DigitalJack]

I do appreciate the doc strings. If only more people would write them. Weavejester's code I think is a fine example of doing this well. https://github.com/weavejester/compojure/blob/master/src/com...