On Apr 19, 2013, at 18:37, u1204 wrote:
> TL:DR
>
> Write ideas for humans around your code or it will die.
> Explain, don't document.
TL:DR "Computers should document.
Humans should explain."
More explicitly:
"Computers should document the things they can.
Humans get to (discover and) explain the rest."
Unfortunately, as my friend Gene Dronek recently snarked at me:
"You mean documentation is _still_ a problem?
The Bad News is that documentation is still a problem. The Good News is that
there are many interesting ideas (and even some working code). So, prospects
are good for a content-agnostic, extensible "system documentation system".
For example, a production-ready, drop-in version of Codeq (with help from
packages such as Analyze, Clojure, Datomic, Lamina, Simulant, Storm, etc).
Such a system could "listen" (in soft real-time) for events from system(s)
it is documenting (eg, file commits, test or production runs, etc. The data
would be stored in an immutable, highly scalable database (Datomic) and made
available using assorted web technology (eg, D3, Pedestal, SVG).
Putting together a production system would certainly require a lot of work,
but it is largely "a simple matter of software" (:-). We have an abundance
of nifty looking components and ideas; they only need to be integrated into
a "drop-in" tool for an existing development shop, server environment, etc.
It's pretty clear that many folks in the development community are down on
documentation, at least in the form that it gets presented to them. However,
few of us would complain about having such a mechanized documentation system,
particularly when chasing down an obscure interaction or symptom.
And, if the system is truly content-agnostic, it can accept information from
humans (eg, facts, files, opinions, rules, text). These can supplement or
help it to generate its explanations. If humans can be cajoled, coerced, or
convinced to jot down their understandings, the available "knowledge base"
can be greatly enhanced over things that mechanized analysis can provide.
Connascence (loosely, coupling or related entities) is a prime example of an
area where mechanized analysis could be useful. We all try to perform "safe
coupling", but most of us don't always succeed. In any case, unsafe coupling
is rife in most APIs, commercial software, and running production systems.
In short, connascence is a fact of life. So, a simple question: how much of
it is well documented (let alone explained)? Followed by: how much of it
can a computer detect? I don't know, but I'd love to find out...
-r
Jim Weirich explains connascence quite well in his "Grand Unified Theory of
Software Design" talk. The "Aloha on Rails" video (http://vimeo.com/10837903)
segues from Maxwell through SOLID to coupling and connascence in name choices,
data formats, and more (:-).
Unfortunately, the slides for this talk seem to have gone AWOL on vimeo, but
a clean and complete set of slides seems to be available in this Git download:
https://github.com/jimweirich/presentation_connascence
See Connascence.key.pdf
In any case, this version has good slides (and the most critical material):
The Grand Unified Theory...
http://aac2009.confreaks.com/06-feb-2009-11-00-the-grand-unified-theory-jim-weirich.html
--
http://www.cfcl.com/rdm Rich Morin
http://www.cfcl.com/rdm/resume r...@cfcl.com
http://www.cfcl.com/rdm/weblog +1 650-873-7841
Software system design, development, and documentation
--
--
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/groups/opt_out.
