On Sat, May 3, 2014 at 3:46 PM, Val Waeselynck <val.vval...@gmail.com>wrote:
> All right, I'll give it a try, here are some thoughts :
>
> I think it's too hard make precise requirements for advanced features in
> advance; I'd rather find a way to let usage drive us in the right
> direction. However, there are a few principles that we know will be wise to
> follow :
>
> - encouraging separation of concerns
> - avoiding duplication of logic
>
> And indeed as a programming language, Clojure follow these very well in
> many respects.
>
> Applying these to the topic of documentation, I think it's a good idea
> to make the documentation system/process separate the concerns of writing
> quality code and making understandable. That seems to make a case towards
> documenting with tests/examples/schemas and against literate programming
> (was that your point, Gregg?)
>
Hi Val, sorry for getting back to you so late (was in the process of moving
to a new apartment the last few weeks so had intermittent web access).
My original comment on litprog ("bad bad bad") was admittedly a little
strong. I think its bad for some things, fine for others. And it's
possible litprog conventions will evolve to address the problems some of us
see with using it for programming in the large etc.
As for documenting with "tests/examples/schemas", I'm somewhere in that
general vicinity, but I think much more needs to be said about just what
that means, and what sort of norms should apply in each case. See for
example https://github.com/mobileink/codegenres/wiki/Tests-as-Documentation(and
feel free to edit, it's just ideas now).
BTW, I discovered the links at
https://github.com/mobileink/codegenres/wikiwere broken; they're fixed
now.
- and maybe also against using types for documenting, but that's really my
> own personal feeling and I don't have any evidence for it.
>
Not sure what you mean; I consider type annotations (hints, whatever)
essential to good documentation.
-Gregg
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
