Discussion:
ANN How To Make Your Open Source Project Awesome (or: Not Suck)
(too old to reply)
Michael Klishin
2013-04-19 22:09:38 UTC
Permalink
Month after month there are more and more people who announce their open
source
Clojure projects. This is great and we can't get enough of this.

What is not great is how easy it often is to get started with some of the
projects.
Some of the most basic "maintainer best practices" are completely ignored,
even though
it often takes 3 minutes to fix some annoyances.

So I wrote a little ranty blog post about what you can do to make your
project awesome
(or at least not suck). This also sums up what we've been trying to
practice with
ClojureWerkz.

I hope it will help the Clojure community to be better library maintainers.
Here it is:
http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/

Now you have no excuse to not make your library totally awesome.
--
MK

http://github.com/michaelklishin
http://twitter.com/michaelklishin

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Raoul Duke
2013-04-19 22:13:03 UTC
Permalink
hooray! right on! testify, brother!!!

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
u1204
2013-04-20 01:37:52 UTC
Permalink
X-Received: by 10.50.6.135 with SMTP id b7mr2781589iga.9.1366421890074;
Fri, 19 Apr 2013 18:38:10 -0700 (PDT)
X-BeenThere: ***@googlegroups.com
Received: by 10.50.104.232 with SMTP id gh8ls848736igb.20.canary; Fri, 19 Apr
2013 18:37:57 -0700 (PDT)
X-Received: by 10.50.130.9 with SMTP id oa9mr5407820igb.1.1366421877110;
Fri, 19 Apr 2013 18:37:57 -0700 (PDT)
Received: from axiom-developer.org (vs338.rosehosting.com. [209.135.140.38])
by gmr-mx.google.com with ESMTPS id mk7si446426igc.0.2013.04.19.18.37.56
for <***@googlegroups.com>
(version=TLSv1 cipher=RC4-SHA bits=128/128);
Fri, 19 Apr 2013 18:37:56 -0700 (PDT)
Received-SPF: neutral (google.com: 209.135.140.38 is neither permitted nor denied by best guess record for domain of ***@axiom-developer.org) client-ip=209.135.140.38;
Received: from u1204 (dynamic-acs-72-23-235-203.zoominternet.net [72.23.235.203])
by axiom-developer.org (8.12.8/8.12.8) with ESMTP id r3K1brse021849
for <***@googlegroups.com>; Fri, 19 Apr 2013 20:37:54 -0500
Received: by u1204 (Postfix, from userid 1000)
id 5214C6872D; Fri, 19 Apr 2013 21:37:52 -0400 (EDT)
In-Reply-To: <CAE3HoVSEP0TAgmcVUrE5sj7L=***@mail.gmail.com> (message from Michael Klishin on Sat, 20 Apr 2013 02:09:38 +0400)
X-Original-Sender: ***@axiom-developer.org
X-Original-Authentication-Results: gmr-mx.google.com; spf=neutral
(google.com: 209.135.140.38 is neither permitted nor denied by best guess
record for domain of ***@axiom-developer.org) smtp.mail=***@axiom-developer.org
Precedence: list
Mailing-list: list ***@googlegroups.com; contact clojure+***@googlegroups.com
List-ID: <clojure.googlegroups.com>
X-Google-Group-Id: 999298108703
List-Post: <http://groups.google.com/group/clojure/post?hl=en_US>, <mailto:***@googlegroups.com>
List-Help: <http://groups.google.com/support/?hl=en_US>, <mailto:clojure+***@googlegroups.com>
List-Archive: <http://groups.google.com/group/clojure?hl=en_US>
Sender: ***@googlegroups.com
List-Subscribe: <http://groups.google.com/group/clojure/subscribe?hl=en_US>, <mailto:clojure+***@googlegroups.com>
List-Unsubscribe: <http://groups.google.com/group/clojure/subscribe?hl=en_US>, <mailto:googlegroups-manage+999298108703+***@googlegroups.com>
Archived-At: <http://permalink.gmane.org/gmane.comp.java.clojure.user/71027>

TL:DR

Write ideas for humans around your code or it will die.
Explain, don't document.



Excellent blog post. However, you write

Passing It Over
At some point you may become disinterested in maintaining your
project. Maybe you've moved on to a new job or no longer use
your own project. Announce it on the mailing list, ask someone to
take over your project. Sooner or later, someone will help. ...

No, no, they won't. Why? Because, as you state earlier:

Claim that people who are not willing to read the code to figure
out even the most basic things are stupid and should flip burgers
instead.

There is a HUGE gulf between the user documentation and maintaining
the code. Just like there is a huge difference between using a car
and maintaining a car.

I have been trying to reverse-engineer the code the Clojure code base.
It uses red-black trees overlaid with a special immutable bit of
design. It uses a lot of optimizations, some of which assume a 32-bit
implementation. All without a comment anywhere. This is excellent code.

It is also unmaintainable.




(aside: the word "you" below is not aimed at the Michael, it is generic.
I am following Michael's usage and style from his blog post.)



.... /me drags out his street-worn soapbox. A crowd of two gathers.

Nobody, nobody, and I say again, NOBODY is going to pick up your
project. Why? Because they are going to look at your code pile and
cringe. There are thousands of good projects in Sourceforge.
Dead ones all. You too are writing dead code.

You have written layer upon layer upon layer of "improvements". You have
added partially worked out "features". You have removed the front-end
code but left the old code there because it is backward compatible with
version 0.0.0.1.2 which was never released.

Just to add to the confusion, you have ported your code to a dozen
platforms so you now have compiler switches, annotations, pragmas,
special Makefile stanzas, and library dependencies that will fail at the
next upgrade. You wrote autoconf macro scripts nobody understands.

You have install scripts for linux, an installer for Windows, and one
for the MAC. However, the linux script uses tools and directories that
only exist on your machine. The Windows installer is for Windows NT,
not Windows 8. The MAC installer doesn't check dependencies so it
installs but fails to run.

You need slime and leiningen but EVERYBODY has moved to smegle and
buildme. Leiningen is now 7 versions ahead of your version with
plugins that conflict with yours so your code no longer installs.

But not a word of explanation on any of it.

Your project is unmaintainable.




.... /me stacks another soapbox, with guitar for a ballad. The crowd thins.

Consider GNU Common Lisp, GCL.
It was originally called Austin Kyoto Common Lisp, AKCL.
It was written by Bill Schelter.

Bill was a FANTASTIC open source developer. He sat at my desk writing
AKCL. He found a bug in emacs, fetched a copy, fixed it, and uploaed
a patched version. In 1985. He was hardcore. He wrote amazing code
and never wrote comments, like all the greats.
AKCL eventually became GCL.

Bill is now dead. GCL was picked up by Camm Macquire. Camm is
another of those precious-few heavy hackers and GCL was the basis
of several huge projects. But Common Lisp has a real standard.
Does your project? Have a hundred people written a standard for you?

What is not explained is the crufty way that AKCL is built. It is
built on top of Kyoto Common Lisp. The Kyoto Common Lisp (KCL) license
says that you can't modify the code. It must be distributed unmodified.
So Bill wrote a "delta" program and everything he wrote was in delta
files off the original, unmodified KCL sources.

Thus, to maintain AKCL source code you have to use patch files.
Bill wrote valid patch files by hand. Diff -Naur valid files without diff.
Hardcore enough for you? Can you read directories full of patch files?

Oh, yeah, and since he was muttering to himself (aka programming)
he didn't even explain why the code needed to be written as patches.
The only reason I know is that I helped write pieces of AKCL and he
sat in my office.

Bill was an amazing programmer. But I now know he did it wrong.



.... /me stacks a bar of soap on top of the pile, steps up and ...

SCREAMS.

Maintaining and modifying source code is hard.
Porting it to multiple new platforms may require rewrites.
Maintaining library compatibility may require refactoring.
Upgrading installers may require code reorganizations.
Contributing it to debian may require restructuring.

It is all trivial and obvious to you. You wrote it. But finding and
fixing the fencepost bug in a red-black immutable tree implementation
borders on the impossible. You need to know that bit 31 overflows in a
strange way only on Alpha2 processors, causing a interrupt that is not
handled by the JVM. What does bit 31 mean? Why did the bug depend on it?

Your project exceeds 25,000 lines of code and every line counts. That's
approximately the number of lines in a 300 page textbook. Drag out any
mathematics reference book that has 300 pages of equations without
words. It's all there. Read the equations. Perfectly correct and
clear. However, it assumes you know a lot.

THAT's what you're saying to the next person to maintain your code.
It's all there. Read the code. Perfectly correct and clear.



.... /me looks down from the height with a weary eye ...

I got my own code back years after I wrote it.
I knew exactly what the code does.
I knew every byte that the compiler will lay down.
I knew how the data structure will be modified.

I wrote the code but I don't know WHY.
I knew it was needed because when I took it out the system broke.
I had to reverse-engineer the "why" of my own code.

It is VERY hard to reverse-engineer WHY someone wrote code.
There are no clues.

If you want your code to live, that is, if you want your code to
be used beyond your involvement you need to EXPLAIN THE CODE.

No, I don't mean Javadoc or Doxygen or any other code-decorating,
push-the-button, tree-killing, automated extraction thingie.

I mean that you need to write words that communicate IDEAS from
human to human. Real sentences with real words that you would say
to someone looking at the code. Functions should have a paragraph of
words. Code reviews should require an explanation with the code
before allowing it into the repository.

If you don't communicate the idea embodied in a piece of code in
words humans can understand, you are writing dead code for yourself.

If you want your code to LIVE, write WORDS for other HUMANS. Lots of
words. More words than code. Think of the difference between a math
reference textbook and a regular math book. Words.

I strongly recommend literate programming but feel free to ignore that.
Write words.

Tim Daly
Curmudgeon at Large

(see http://axiom-developer.org/axiom-website/litprog.html )









--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Michael Klishin
2013-04-20 04:11:59 UTC
Permalink
2013/4/20 u1204 <***@axiom-developer.org>

> There is a HUGE gulf between the user documentation and maintaining
> the code. Just like there is a huge difference between using a car
> and maintaining a car.
>

There are two things to consider:

* Your audience is other developers.
* Most projects are relatively small and straightforward compared to the
Clojure compiler.

My point was "at least try to find a new maintainer". Don't let it rot.

There is a blog post in the community that I'm referring to between the
lines.
It won't be hard to figure out which one. The idea is, "don't do that".
Don't turn
your project into abandonware if you no longer want to maintain it well.

Projects such as ring, clj-time, clj-http have found new
maintainers and those people do a great job with them.
--
MK

http://github.com/michaelklishin
http://twitter.com/michaelklishin

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
juan.facorro
2013-04-20 06:06:25 UTC
Permalink
Good stuff and I really enjoyed reading it too.

Thanks,

J

On Saturday, April 20, 2013 1:11:59 AM UTC-3, Michael Klishin wrote:
>
>
> 2013/4/20 u1204 <***@axiom-developer.org <javascript:>>
>
>> There is a HUGE gulf between the user documentation and maintaining
>> the code. Just like there is a huge difference between using a car
>> and maintaining a car.
>>
>
> There are two things to consider:
>
> * Your audience is other developers.
> * Most projects are relatively small and straightforward compared to the
> Clojure compiler.
>
> My point was "at least try to find a new maintainer". Don't let it rot.
>
> There is a blog post in the community that I'm referring to between the
> lines.
> It won't be hard to figure out which one. The idea is, "don't do that".
> Don't turn
> your project into abandonware if you no longer want to maintain it well.
>
> Projects such as ring, clj-time, clj-http have found new
> maintainers and those people do a great job with them.
> --
> MK
>
> http://github.com/michaelklishin
> http://twitter.com/michaelklishin
>

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Phil Hagelberg
2013-04-20 15:52:29 UTC
Permalink
Michael Klishin writes:

> My point was "at least try to find a new maintainer". Don't let it rot.

I see where you're coming from, but there's definitely a place for
phasing out a project gracefully. The majority of projects will have no
users outside the original author, and that's fine. There are even cases
where it's best for a widely-used library to pass on the torch and have
its users migrate to an alternative that's widely understood to be
superior. (clojure-json, noir, even monolithic clojure-contrib arguably,
etc) So it's not quite as black and white as the post makes it sound.

However, just spluttering out and going dark is obviously not what you
want; if there's a transition to be done it must be clearly communicated.

Anyway, everything else about the post appears solid except for one
thing. It recommends the MIT license, which has no patent protection
whatsoever; this could open you and your users up to liabilities in ways
that are impossible to predict given that the United States Patent
Office's tendency to grant patents without examining them first. So I
strongly caution against using licenses which don't include patent grant
clauses unless it's for throw-away code. While the Apache license can be
annoying in all the boilerplate it requires, at least it doesn't have
this problem.

-Phil
John Gabriele
2013-04-20 19:40:06 UTC
Permalink
On Saturday, April 20, 2013 11:52:29 AM UTC-4, Phil Hagelberg wrote:
>
>
>
> Anyway, everything else about the post appears solid except for one
> thing. It recommends the MIT license, which has no patent protection
> whatsoever; this could open you and your users up to liabilities in ways
> that are impossible to predict given that the United States Patent
> Office's tendency to grant patents without examining them first. So I
> strongly caution against using licenses which don't include patent grant
> clauses unless it's for throw-away code. While the Apache license can be
> annoying in all the boilerplate it requires, at least it doesn't have
> this problem.
>
> Glad you brought this up, Phil.

My rules of thumb are:

* if you want copyleft, *and* wish to require those incorporating your
code into their own program to also copyleft, use GPL,
* if you want copyleft for just your own code, use LGPL,
* otherwise, if you want a more permissive license, use Apache 2.

I think those three choices cover the bases pretty well.

---John

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Michael Klishin
2013-04-20 20:12:22 UTC
Permalink
2013/4/20 Phil Hagelberg <***@hagelb.org>

> Anyway, everything else about the post appears solid except for one
> thing. It recommends the MIT license, which has no patent protection
> whatsoever; this could open you and your users up to liabilities in ways
> that are impossible to predict given that the United States Patent
> Office's tendency to grant patents without examining them first. So I
> strongly caution against using licenses which don't include patent grant
> clauses unless it's for throw-away code. While the Apache license can be
> annoying in all the boilerplate it requires, at least it doesn't have
> this problem.
>

Ii wasn't immediately clear to me, but it makes sense, given how short
the MIT license is.

What licenses does it make sense to recommend?

I'll update the post because, indeed, we [maintainers] can't ignore patent
protection.
--
MK

http://github.com/michaelklishin
http://twitter.com/michaelklishin

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Phil Hagelberg
2013-04-20 20:50:35 UTC
Permalink
Michael Klishin writes:

> It wasn't immediately clear to me, but it makes sense, given how short
> the MIT license is.
>
> What licenses does it make sense to recommend?

Given that Clojure libraries must be compatible with Clojure's license,
the GPL is ruled out. I recommend the EPL; it's what you get when you
run `lein new myproject`, and I feel like Rich made a pragmatic choice
with a license that is copyleft without being virally so.

If there is some reason you want to avoid copyleft, (corporate paranoia,
etc.) then the Apache license seems like the best bet among non-copyleft
ones, though the requirement that it be included in *every* single file
is very annoying. However, I don't know of any other non-copyleft
licenses which offer good patent protection.

It's also worth noting that simply placing your software in the public
domain is a bad idea since several European legal systems don't have a
concept of public domain. If you want to completely disavow copyright on
your work the best choice seems to be the creative-commons-based CC0,
which places your work in the public domain where possible but contains
exceptions for jurisdictions where it's not:

https://creativecommons.org/publicdomain/zero/1.0/legalcode

It should go without saying, but don't take this as legal advice, etc;
please consult a legal professional before doing anything serious.

-Phil

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
John Gabriele
2013-04-20 22:18:02 UTC
Permalink
On Saturday, April 20, 2013 4:50:35 PM UTC-4, Phil Hagelberg wrote:
>
>
> I recommend the EPL; it's what you get when you
> run `lein new myproject`, and I feel like Rich made a pragmatic choice
> with a license that is copyleft without being virally so.
>


My understanding is that "copyleft" roughly means, "any changes you make to
the program (and then subsequently distribute) must be licensed under the
same terms as the original program".

The EPL only appears to be copyleft if the contributor *chooses* to
distribute the source code along with the object code. They can just as
well choose to distribute object code only.

(If you want to guarantee that your source code --- plus future
(distributed) modifications by others --- remains free, the LGPL would be a
good choice.)


> If there is some reason you want to avoid copyleft, (corporate paranoia,
> etc.) then the Apache license seems like the best bet among non-copyleft
> ones, {snip}
>

Agreed.

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Michael Klishin
2013-04-20 22:26:14 UTC
Permalink
2013/4/21 Phil Hagelberg <***@hagelb.org>

> It should go without saying, but don't take this as legal advice, etc;
> please consult a legal professional before doing anything serious.
>

Definitely.

I finally found the site I wanted to link to, TL;DR Legal:
http://www.tldrlegal.com/

Great overview of OSS licenses in plain English.
--
MK

http://github.com/michaelklishin
http://twitter.com/michaelklishin

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Cedric Greevey
2013-04-20 22:38:38 UTC
Permalink
On Sat, Apr 20, 2013 at 6:26 PM, Michael Klishin <
***@gmail.com> wrote:

>
> 2013/4/21 Phil Hagelberg <***@hagelb.org>
>
>> It should go without saying, but don't take this as legal advice, etc;
>> please consult a legal professional before doing anything serious.
>>
>
> Definitely.
>

That's very nice in theory; in practice, though, many contributors to and
initiators of open source projects are hobbyist programmers that can't
afford to spend $500/hr consulting a lawyer each time they want to decide
on a license for a project.

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Michael Klishin
2013-04-21 04:19:20 UTC
Permalink
2013/4/21 Cedric Greevey <***@gmail.com>

> That's very nice in theory; in practice, though, many contributors to and
> initiators of open source projects are hobbyist programmers that can't
> afford to spend $500/hr consulting a lawyer each time they want to decide
> on a license for a project.


I was referring to "don't take this as legal advice, etc".
--
MK

http://github.com/michaelklishin
http://twitter.com/michaelklishin

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Phillip Lord
2013-04-22 13:10:07 UTC
Permalink
Phil Hagelberg <***@hagelb.org> writes:

> Michael Klishin writes:
>
>> It wasn't immediately clear to me, but it makes sense, given how short
>> the MIT license is.
>>
>> What licenses does it make sense to recommend?
>
> Given that Clojure libraries must be compatible with Clojure's license,
> the GPL is ruled out.


I used to think that this was true, but actually I think it is not. The
GPL specifically talks about "standard interfaces". So you *could* build
a library or a tool that used GPL, and "linking" through to
clojure.core. The clojure.core libraries would not need to be GPL, and
the incompatability with EPL would not matter.

This would not extent to all libraries, though. So, for example, I would
not link a GPL library to https://github.com/technomancy/robert-hooke
legally (you could but that's a different issue!).



> I recommend the EPL; it's what you get when you run `lein new
> myproject`, and I feel like Rich made a pragmatic choice with a
> license that is copyleft without being virally so.

To my mind, choice of law clauses are poor. Why would I want to go to
New York to assert my legal rights for my code?


> If there is some reason you want to avoid copyleft, (corporate paranoia,
> etc.) then the Apache license seems like the best bet among non-copyleft
> ones, though the requirement that it be included in *every* single file
> is very annoying.

Just the boilerplate surely?


Phil

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
John Gabriele
2013-04-20 16:44:00 UTC
Permalink
On Friday, April 19, 2013 9:37:52 PM UTC-4, ***@axiom-developer.org wrote:
>
> TL:DR
>
> Write ideas for humans around your code or it will die.
> Explain, don't document.
>
>
Excellent post, Tim. Thanks for writing it all up.

Though, I tend to think that "documenting" is the same as "explaining"
(what good is documentation if it doesn't explain?).


> I mean that you need to write words that communicate IDEAS from
> human to human. Real sentences with real words that you would say
> to someone looking at the code.
>

If you don't communicate the idea embodied in a piece of code in
> words humans can understand, you are writing dead code for yourself.
>
>
Yes.


> If you want your code to LIVE, write WORDS for other HUMANS. Lots of
> words. More words than code. Think of the difference between a math
> reference textbook and a regular math book. Words.
>
>
One minor point to add: It's easy to write too much. To meander. Concision
is hard.


> I strongly recommend literate programming but feel free to ignore that.
> Write words.
>
>
Hm. Maybe I should ask this off-list, but, in a nutshell, is literate
programming:

1. put possibly-out-of-order specially-marked (with an id) code snippets
throughout your doc,
2. also put an *ordered* listing of all the id's somewhere in your doc,
3. use tools to find that ordered list of ids, then extract the snippets,
put them in order, and glue them all together so they can be compiled/run?

Thanks,
---John

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
u1204
2013-04-20 18:51:06 UTC
Permalink
X-Received: by 10.49.72.194 with SMTP id f2mr2003907qev.34.1366483897142;
Sat, 20 Apr 2013 11:51:37 -0700 (PDT)
X-BeenThere: ***@googlegroups.com
Received: by 10.49.27.10 with SMTP id p10ls2701650qeg.60.gmail; Sat, 20 Apr
2013 11:51:07 -0700 (PDT)
X-Received: by 10.236.111.106 with SMTP id v70mr10111949yhg.34.1366483867665;
Sat, 20 Apr 2013 11:51:07 -0700 (PDT)
Received: from axiom-developer.org (vs338.rosehosting.com. [209.135.140.38])
by gmr-mx.google.com with ESMTPS id ex5si778715igc.1.2013.04.20.11.51.07
(version=TLSv1 cipher=RC4-SHA bits=128/128);
Sat, 20 Apr 2013 11:51:07 -0700 (PDT)
Received-SPF: neutral (google.com: 209.135.140.38 is neither permitted nor denied by best guess record for domain of ***@axiom-developer.org) client-ip=209.135.140.38;
Received: from u1204 (dynamic-acs-72-23-235-203.zoominternet.net [72.23.235.203])
by axiom-developer.org (8.12.8/8.12.8) with ESMTP id r3KIp6se024935
for <***@googlegroups.com>; Sat, 20 Apr 2013 13:51:06 -0500
Received: by u1204 (Postfix, from userid 1000)
id 516BC68778; Sat, 20 Apr 2013 14:51:06 -0400 (EDT)
In-Reply-To: <548bdb26-42f5-44b7-968e-***@googlegroups.com> (message from John Gabriele on Sat, 20 Apr 2013 09:44:00 -0700 (PDT))
X-Original-Sender: ***@axiom-developer.org
X-Original-Authentication-Results: gmr-mx.google.com; spf=neutral
(google.com: 209.135.140.38 is neither permitted nor denied by best guess
record for domain of ***@axiom-developer.org) smtp.mail=***@axiom-developer.org
Precedence: list
Mailing-list: list ***@googlegroups.com; contact clojure+***@googlegroups.com
List-ID: <clojure.googlegroups.com>
X-Google-Group-Id: 999298108703
List-Post: <http://groups.google.com/group/clojure/post?hl=en_US>, <mailto:***@googlegroups.com>
List-Help: <http://groups.google.com/support/?hl=en_US>, <mailto:clojure+***@googlegroups.com>
List-Archive: <http://groups.google.com/group/clojure?hl=en_US>
Sender: ***@googlegroups.com
List-Subscribe: <http://groups.google.com/group/clojure/subscribe?hl=en_US>, <mailto:clojure+***@googlegroups.com>
List-Unsubscribe: <http://groups.google.com/group/clojure/subscribe?hl=en_US>, <mailto:googlegroups-manage+999298108703+***@googlegroups.com>
Archived-At: <http://permalink.gmane.org/gmane.comp.java.clojure.user/71043>

>> TL:DR
>>
>> Write ideas for humans around your code or it will die.
>> Explain, don't document.
>>
>>
>Excellent post, Tim. Thanks for writing it all up.
>
>Though, I tend to think that "documenting" is the same as "explaining"
>(what good is documentation if it doesn't explain?).

The word "explain" is semantically the same as "document" to most
people but not to the programmer community.

I chose the word "explain" carefully. The word "document" has negative
emotional overtones for programmers. It usually implies fulfilling
checklist requirements like "Does it have a Javadoc stanza?".

I just gave a talk at the WriteTheDocs conference. People who do
this for a living ("documentarians") were proposing creating games
like "document like a pirate day" to "entice programmers to document".

Personally, I see documentation as a mark of a professional.
Rise to the standard or retire into management.

Tim Daly
Curmudgeon at Large

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Ben Wolfson
2013-04-20 19:13:28 UTC
Permalink
On Sat, Apr 20, 2013 at 11:51 AM, u1204 <***@axiom-developer.org> wrote:

>
> The word "explain" is semantically the same as "document" to most
> people but not to the programmer community.
>

FWIW, I think the situation is closer to precisely the opposite. If I ask
you to document what you do today, what will you do? Hold on to your
receipts? Log mileage in your car? Compare being asked to explain what you
do today.

--
Ben Wolfson
"Human kind has used its intelligence to vary the flavour of drinks, which
may be sweet, aromatic, fermented or spirit-based. ... Family and social
life also offer numerous other occasions to consume drinks for pleasure."
[Larousse, "Drink" entry]

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
u1204
2013-04-20 19:44:29 UTC
Permalink
X-Received: by 10.50.50.205 with SMTP id e13mr56223igo.4.1366487085237;
Sat, 20 Apr 2013 12:44:45 -0700 (PDT)
X-BeenThere: ***@googlegroups.com
Received: by 10.50.67.36 with SMTP id k4ls1171914igt.7.canary; Sat, 20 Apr
2013 12:44:30 -0700 (PDT)
X-Received: by 10.43.70.9 with SMTP id ye9mr15635531icb.12.1366487070053;
Sat, 20 Apr 2013 12:44:30 -0700 (PDT)
Received: from axiom-developer.org (vs338.rosehosting.com. [209.135.140.38])
by gmr-mx.google.com with ESMTPS id o6si794334igh.2.2013.04.20.12.44.29
for <***@googlegroups.com>
(version=TLSv1 cipher=RC4-SHA bits=128/128);
Sat, 20 Apr 2013 12:44:30 -0700 (PDT)
Received-SPF: neutral (google.com: 209.135.140.38 is neither permitted nor denied by best guess record for domain of ***@axiom-developer.org) client-ip=209.135.140.38;
Received: from u1204 (dynamic-acs-72-23-235-203.zoominternet.net [72.23.235.203])
by axiom-developer.org (8.12.8/8.12.8) with ESMTP id r3KJiTse025045
for <***@googlegroups.com>; Sat, 20 Apr 2013 14:44:29 -0500
Received: by u1204 (Postfix, from userid 1000)
id 48D6D68778; Sat, 20 Apr 2013 15:44:29 -0400 (EDT)
In-Reply-To: <CAPc-aXmnsBTg2iSZSLz1rT-VqzoLskx_PwToMrMQtX6h-***@mail.gmail.com> (message from Ben Wolfson on Sat, 20 Apr 2013 12:13:28 -0700)
X-Original-Sender: ***@axiom-developer.org
X-Original-Authentication-Results: gmr-mx.google.com; spf=neutral
(google.com: 209.135.140.38 is neither permitted nor denied by best guess
record for domain of ***@axiom-developer.org) smtp.mail=***@axiom-developer.org
Precedence: list
Mailing-list: list ***@googlegroups.com; contact clojure+***@googlegroups.com
List-ID: <clojure.googlegroups.com>
X-Google-Group-Id: 999298108703
List-Post: <http://groups.google.com/group/clojure/post?hl=en_US>, <mailto:***@googlegroups.com>
List-Help: <http://groups.google.com/support/?hl=en_US>, <mailto:clojure+***@googlegroups.com>
List-Archive: <http://groups.google.com/group/clojure?hl=en_US>
Sender: ***@googlegroups.com
List-Subscribe: <http://groups.google.com/group/clojure/subscribe?hl=en_US>, <mailto:clojure+***@googlegroups.com>
List-Unsubscribe: <http://groups.google.com/group/clojure/subscribe?hl=en_US>, <mailto:googlegroups-manage+999298108703+***@googlegroups.com>
Archived-At: <http://permalink.gmane.org/gmane.comp.java.clojure.user/71047>

>> The word "explain" is semantically the same as "document" to most
>> people but not to the programmer community.
>>
>
>FWIW, I think the situation is closer to precisely the opposite. If I ask
>you to document what you do today, what will you do? Hold on to your
>receipts? Log mileage in your car? Compare being asked to explain what you
>do today.

Precisely my point (unless I miss your point). If I ask you to document
your trip you'll hand me receipts. If I ask you to explain your trip you
need to tell me why you went, what you did, and why I care.

Current documentation tools and standards attach an explanation to the
trip receipt ("I ate here"). What we need to keep a program alive is the
explanation of why you did it, what you did (the inline code), and why I
care.

Tim Daly

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Ben Wolfson
2013-04-20 19:58:34 UTC
Permalink
On Sat, Apr 20, 2013 at 12:44 PM, u1204 <***@axiom-developer.org> wrote:

> >> The word "explain" is semantically the same as "document" to most
> >> people but not to the programmer community.
> >>
> >
> >FWIW, I think the situation is closer to precisely the opposite. If I ask
> >you to document what you do today, what will you do? Hold on to your
> >receipts? Log mileage in your car? Compare being asked to explain what you
> >do today.
>
> Precisely my point (unless I miss your point). If I ask you to document
> your trip you'll hand me receipts. If I ask you to explain your trip you
> need to tell me why you went, what you did, and why I care.


My point was that "most people" will do the same (provide documents vs.
contextualize the actions).

--
Ben Wolfson
"Human kind has used its intelligence to vary the flavour of drinks, which
may be sweet, aromatic, fermented or spirit-based. ... Family and social
life also offer numerous other occasions to consume drinks for pleasure."
[Larousse, "Drink" entry]

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
u1204
2013-04-20 19:35:04 UTC
Permalink
X-Received: by 10.50.130.113 with SMTP id od17mr1075710igb.7.1366486521107;
Sat, 20 Apr 2013 12:35:21 -0700 (PDT)
X-BeenThere: ***@googlegroups.com
Received: by 10.50.42.136 with SMTP id o8ls1178365igl.38.canary; Sat, 20 Apr
2013 12:35:07 -0700 (PDT)
X-Received: by 10.43.125.1 with SMTP id gq1mr15703701icc.10.1366486507361;
Sat, 20 Apr 2013 12:35:07 -0700 (PDT)
Received: from axiom-developer.org (vs338.rosehosting.com. [209.135.140.38])
by gmr-mx.google.com with ESMTPS id dl10si856018igb.0.2013.04.20.12.35.07
for <***@googlegroups.com>
(version=TLSv1 cipher=RC4-SHA bits=128/128);
Sat, 20 Apr 2013 12:35:07 -0700 (PDT)
Received-SPF: neutral (google.com: 209.135.140.38 is neither permitted nor denied by best guess record for domain of ***@axiom-developer.org) client-ip=209.135.140.38;
Received: from u1204 (dynamic-acs-72-23-235-203.zoominternet.net [72.23.235.203])
by axiom-developer.org (8.12.8/8.12.8) with ESMTP id r3KJZ4se025021
for <***@googlegroups.com>; Sat, 20 Apr 2013 14:35:06 -0500
Received: by u1204 (Postfix, from userid 1000)
id E6DA468778; Sat, 20 Apr 2013 15:35:04 -0400 (EDT)
In-Reply-To: <548bdb26-42f5-44b7-968e-***@googlegroups.com> (message from John Gabriele on Sat, 20 Apr 2013 09:44:00 -0700 (PDT))
X-Original-Sender: ***@axiom-developer.org
X-Original-Authentication-Results: gmr-mx.google.com; spf=neutral
(google.com: 209.135.140.38 is neither permitted nor denied by best guess
record for domain of ***@axiom-developer.org) smtp.mail=***@axiom-developer.org
Precedence: list
Mailing-list: list ***@googlegroups.com; contact clojure+***@googlegroups.com
List-ID: <clojure.googlegroups.com>
X-Google-Group-Id: 999298108703
List-Post: <http://groups.google.com/group/clojure/post?hl=en_US>, <mailto:***@googlegroups.com>
List-Help: <http://groups.google.com/support/?hl=en_US>, <mailto:clojure+***@googlegroups.com>
List-Archive: <http://groups.google.com/group/clojure?hl=en_US>
Sender: ***@googlegroups.com
List-Subscribe: <http://groups.google.com/group/clojure/subscribe?hl=en_US>, <mailto:clojure+***@googlegroups.com>
List-Unsubscribe: <http://groups.google.com/group/clojure/subscribe?hl=en_US>, <mailto:googlegroups-manage+999298108703+***@googlegroups.com>
Archived-At: <http://permalink.gmane.org/gmane.comp.java.clojure.user/71045>

>Hm. Maybe I should ask this off-list, but, in a nutshell, is literate
>programming:

I feel this is an "on-list" topic (although it is obvious that I'm an
edge-case fanatic). Clojure is trying to introduce a lot of new ideas
that change how programming is done. It is an edge-case community.

I'm trying to change the standard to which Clojure programs are
written by introducing a shiny, new edge-case idea (from the 1960s).
High quality Clojure programs should be literate.

>
> 1. put possibly-out-of-order specially-marked (with an id) code snippets
>throughout your doc,
> 2. also put an *ordered* listing of all the id's somewhere in your doc,
> 3. use tools to find that ordered list of ids, then extract the snippets,
>put them in order, and glue them all together so they can be compiled/run?

Programs are written in a certain order because the compiler
requires it. For instance, some code in Clojure is required to
occur before others (e.g. importing code, pre-compiling java).

If you try to explain various ideas and illustrate them with the
REAL code that will be EXECUTED you need to be able to arrange
the code in human order, not machine order.

Most documentation tools (javadoc, doxygen, org-mode, etc.)
associate the explanation with the code rather than associate
the code with the explanation. This prioritizes the machine
over the human. But the point of explanation (not documentation)
is to communicate to a human. These tools miss the point.

A literate program emphasizes human communication over machine
communication. Thus code is introduced in human order. Look at the
book "Lisp in Small Pieces" to get an idea of how well it can be done.

A good explanation starts with motivation. Any writing course
emphasizes "finding the motivation for the character's actions".

In explaining Clojure, for example, you'll find that the motivations
are usually brought forth in a Rich Hickey talk. He talks about the
motivations for immutable data structures, for time and state, for
carrying metadata, and so much more. None of this is in the code base.

If you don't know about immutable data structures then the code
that implements lists is completely inefficient nonsense. It would
traditionally be seen as hanging onto nodes that are "dead" for
no apparent reason. Lacking the motivating explanation any good
programmer would "optimize away" all the cruft, breaking Clojure.

So to explain something to a human you need to motivate it.
To motivate it you need to arrange the thoughts in the proper
order. In a literate program the thoughts are "reduced to practice"
by showing the actual code inline. This implies the ability to
re-arrange code to suit the human.

Ultimately, think of writing code as though you were writing a book.
Let the code fall where it fits best in the chapter where it belongs.
Now you have a work of literature that communicates to a human.
That, I claim, will keep your program alive after you abandon it.

Give someone your program. Send them to Hawaii on a 2 week, all
expense paid vacation. If, when the return, they can maintain and
modify the code as well as the original developers then you have
written a literate program. (aka "the Hawaii test").

Tim Daly





--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
John Gabriele
2013-04-20 19:53:41 UTC
Permalink
On Saturday, April 20, 2013 3:35:04 PM UTC-4, ***@axiom-developer.org
wrote:
> > but, in a nutshell, is literate programming:
>
> >
> > 1. put possibly-out-of-order specially-marked (with an id) code snippets
> >throughout your doc,
> > 2. also put an *ordered* listing of all the id's somewhere in your doc,
> > 3. use tools to find that ordered list of ids, then extract the
> snippets,
> >put them in order, and glue them all together so they can be
> compiled/run?
>
> Programs are written in a certain order because the compiler
> requires it. {snip}
>
> If you try to explain various ideas and illustrate them with the
> REAL code that will be EXECUTED you need to be able to arrange
> the code in human order, not machine order.
>
> ...
>

Ok. So, if "possibly-out-of-order" (in my message above) means "in human
order", is my nutshell summary of how literate programming works correct?

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
u1204
2013-04-20 20:13:42 UTC
Permalink
X-Received: by 10.50.50.205 with SMTP id e13mr59560igo.4.1366488830379;
Sat, 20 Apr 2013 13:13:50 -0700 (PDT)
X-BeenThere: ***@googlegroups.com
Received: by 10.50.119.69 with SMTP id ks5ls1188083igb.15.canary; Sat, 20 Apr
2013 13:13:43 -0700 (PDT)
X-Received: by 10.42.178.2 with SMTP id bk2mr15731290icb.26.1366488823154;
Sat, 20 Apr 2013 13:13:43 -0700 (PDT)
Received: from axiom-developer.org (vs338.rosehosting.com. [209.135.140.38])
by gmr-mx.google.com with ESMTPS id o6si800124igh.2.2013.04.20.13.13.43
for <***@googlegroups.com>
(version=TLSv1 cipher=RC4-SHA bits=128/128);
Sat, 20 Apr 2013 13:13:43 -0700 (PDT)
Received-SPF: neutral (google.com: 209.135.140.38 is neither permitted nor denied by best guess record for domain of ***@axiom-developer.org) client-ip=209.135.140.38;
Received: from u1204 (dynamic-acs-72-23-235-203.zoominternet.net [72.23.235.203])
by axiom-developer.org (8.12.8/8.12.8) with ESMTP id r3KKDgse025087
for <***@googlegroups.com>; Sat, 20 Apr 2013 15:13:42 -0500
Received: by u1204 (Postfix, from userid 1000)
id 9AE7168778; Sat, 20 Apr 2013 16:13:42 -0400 (EDT)
In-Reply-To: <7806b6c1-01bb-458d-a890-***@googlegroups.com> (message from John Gabriele on Sat, 20 Apr 2013 12:53:41 -0700 (PDT))
X-Original-Sender: ***@axiom-developer.org
X-Original-Authentication-Results: gmr-mx.google.com; spf=neutral
(google.com: 209.135.140.38 is neither permitted nor denied by best guess
record for domain of ***@axiom-developer.org) smtp.mail=***@axiom-developer.org
Precedence: list
Mailing-list: list ***@googlegroups.com; contact clojure+***@googlegroups.com
List-ID: <clojure.googlegroups.com>
X-Google-Group-Id: 999298108703
List-Post: <http://groups.google.com/group/clojure/post?hl=en_US>, <mailto:***@googlegroups.com>
List-Help: <http://groups.google.com/support/?hl=en_US>, <mailto:clojure+***@googlegroups.com>
List-Archive: <http://groups.google.com/group/clojure?hl=en_US>
Sender: ***@googlegroups.com
List-Subscribe: <http://groups.google.com/group/clojure/subscribe?hl=en_US>, <mailto:clojure+***@googlegroups.com>
List-Unsubscribe: <http://groups.google.com/group/clojure/subscribe?hl=en_US>, <mailto:googlegroups-manage+999298108703+***@googlegroups.com>
Archived-At: <http://permalink.gmane.org/gmane.comp.java.clojure.user/71051>

>> > but, in a nutshell, is literate programming:
>>
>> >
>> > 1. put possibly-out-of-order specially-marked (with an id) code snippets
>> >throughout your doc,
>> > 2. also put an *ordered* listing of all the id's somewhere in your doc,
>> > 3. use tools to find that ordered list of ids, then extract the
>> snippets,
>> >put them in order, and glue them all together so they can be
>> compiled/run?
>>
>> Programs are written in a certain order because the compiler
>> requires it. {snip}
>>
>> If you try to explain various ideas and illustrate them with the
>> REAL code that will be EXECUTED you need to be able to arrange
>> the code in human order, not machine order.
>>
>> ...
>>
>
>Ok. So, if "possibly-out-of-order" (in my message above) means "in human
>order", is my nutshell summary of how literate programming works correct?

As a technology, yes. See
http://daly.axiom-developer.org/clojure.pdf
http://daly.axiom-developer.org/clojure.pamphlet

You'll notice that the Makefile extracts all of Clojure and all of
the tests back to the directory structure required by the compiler.
The code is introduced out of order in the document.

My only hesitation is that it is important not to equate "literate
programming" with a particular detail. I fear that some bright spot
will add "out of order" to org-mode or javadoc and call it
"literate programming", completely missing the point.

Tim Daly


--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Christian Romney
2013-04-21 14:35:58 UTC
Permalink
"In explaining Clojure, for example, you'll find that the motivations are usually brought forth in a Rich Hickey talk. He talks about the motivations for immutable data structures, for time and state, for carrying metadata, and so much more. None of this is in the code base. "

I can sympathize with this point of view. I also think that Github wikis are a double-edged sword. They're convenient when you're exploring the repository in your browser, and a pain when you're not.

It believe it would be a great first step to take the content from the Clojure website (where Rich has explained immutability, state, persistent data structures, etc) and store them as some variant of plain text (org mode?) in the repo itself.

This is precisely the approach taken by git, for instance. In its Documentation folder you can find not only "man page" style docs, but also docs explaining data structures, motivations, things only contributors need to care about and so on.

Tools can the process these files as well and make websites or wikis out of them. This is not quite the same as literate programming, obviously, but it seems to me to be an easily achievable first step for any project, including Clojure core, with potential benefits that surpass the effort required to make it happen.

P.S. Sorry if the quoting is off...typing from a phone.

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Rich Morin
2013-04-21 00:05:31 UTC
Permalink
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 ***@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 ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Rich Morin
2013-04-29 07:42:52 UTC
Permalink
A clean, if short (32 minute) version of Jim Weirich's talk on connascence
is again online at Confreaks (Thanks, Coby!). See:

The Building Blocks of Modularity, aka
The Grand Unified Theory of Software Development
http://confreaks.com/videos/77-mwrc2009-the-building-blocks-of-modularity

Just as some of Glenford Myers' work in "Composite/Structured Design" fails
to match some aspects of OO development, some of Meilir Page-Jones work in
"What every programmer should know about Object-Oriented Design" fails to
match some aspects of Clojure, FP, etc.

For example, Clojure's handling of identity and value certainly speaks to
the question of "Connascence of Identity". I'm not sure how much effect
immutability has on connascence. Certainly, "using the data as the API"
(as Stuart Sierra recommends) differs markedly from OO best practices.

However, the basic notion of identifying forms of coupling and thinking
about their dangers (and benefits) is still very relevant. If you want
a good introduction to the topic, this is a good video to watch.

-r

--
http://www.cfcl.com/rdm Rich Morin
http://www.cfcl.com/rdm/resume ***@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 ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
AtKaaZ
2013-04-29 12:10:40 UTC
Permalink
Thank you very much.


On Mon, Apr 29, 2013 at 10:42 AM, Rich Morin <***@cfcl.com> wrote:

> A clean, if short (32 minute) version of Jim Weirich's talk on connascence
> is again online at Confreaks (Thanks, Coby!). See:
>
> The Building Blocks of Modularity, aka
> The Grand Unified Theory of Software Development
>
> http://confreaks.com/videos/77-mwrc2009-the-building-blocks-of-modularity
>
> Just as some of Glenford Myers' work in "Composite/Structured Design" fails
> to match some aspects of OO development, some of Meilir Page-Jones work in
> "What every programmer should know about Object-Oriented Design" fails to
> match some aspects of Clojure, FP, etc.
>
> For example, Clojure's handling of identity and value certainly speaks to
> the question of "Connascence of Identity". I'm not sure how much effect
> immutability has on connascence. Certainly, "using the data as the API"
> (as Stuart Sierra recommends) differs markedly from OO best practices.
>
> However, the basic notion of identifying forms of coupling and thinking
> about their dangers (and benefits) is still very relevant. If you want
> a good introduction to the topic, this is a good video to watch.
>
> -r
>
> --
> http://www.cfcl.com/rdm Rich Morin
> http://www.cfcl.com/rdm/resume ***@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 ***@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+***@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+***@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>
>

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Dave Della Costa
2013-04-20 04:08:05 UTC
Permalink
Good points. I've tried to follow many of these with code I've written,
but there are still some things I could stand to do better.

Thanks for writing this, it can serve as a checklist for my own projects
from now on!

Cheers,
DD

(2013/04/20 7:09), Michael Klishin wrote:
> Month after month there are more and more people who announce their open
> source
> Clojure projects. This is great and we can't get enough of this.
>
> What is not great is how easy it often is to get started with some of
> the projects.
> Some of the most basic "maintainer best practices" are completely
> ignored, even though
> it often takes 3 minutes to fix some annoyances.
>
> So I wrote a little ranty blog post about what you can do to make your
> project awesome
> (or at least not suck). This also sums up what we've been trying to
> practice with
> ClojureWerkz.
>
> I hope it will help the Clojure community to be better library
> maintainers. Here it is:
> http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/
>
> Now you have no excuse to not make your library totally awesome.
> --
> MK
>
> http://github.com/michaelklishin
> http://twitter.com/michaelklishin
>
> --
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to ***@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+***@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+***@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Steven Degutis
2013-04-20 21:01:13 UTC
Permalink
Nice write-up. I took some of your advice in releasing Windows.app today:

- Put the source on github: https://github.com/sdegutis/windowsapp
- Made the readme concise and clear
- Added official docs right into the readme
- No longer making any breaking changes to API
- A friend posted about it on HN at
https://news.ycombinator.com/item?id=5582371 (there's no mailing lists for
Mac apps afaik)

I think I covered each major point.

-Steven


On Fri, Apr 19, 2013 at 5:09 PM, Michael Klishin <
***@gmail.com> wrote:

> Month after month there are more and more people who announce their open
> source
> Clojure projects. This is great and we can't get enough of this.
>
> What is not great is how easy it often is to get started with some of the
> projects.
> Some of the most basic "maintainer best practices" are completely ignored,
> even though
> it often takes 3 minutes to fix some annoyances.
>
> So I wrote a little ranty blog post about what you can do to make your
> project awesome
> (or at least not suck). This also sums up what we've been trying to
> practice with
> ClojureWerkz.
>
> I hope it will help the Clojure community to be better library
> maintainers. Here it is:
>
> http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/
>
> Now you have no excuse to not make your library totally awesome.
> --
> MK
>
> http://github.com/michaelklishin
> http://twitter.com/michaelklishin
>
> --
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to ***@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+***@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+***@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>
>

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Michael Klishin
2013-04-20 22:25:22 UTC
Permalink
2013/4/21 Steven Degutis <***@gmail.com>

> A friend posted about it on HN at
> https://news.ycombinator.com/item?id=5582371 (there's no mailing lists
> for Mac apps afaik)
>

Steven,

Sounds great! As for the mailing list, feel free to start a Google group
for your project. It's pretty easy to manage
and easy to join (many have Google accounts).
--
MK

http://github.com/michaelklishin
http://twitter.com/michaelklishin

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Steven Degutis
2013-04-21 00:16:42 UTC
Permalink
Ah, great idea. Thanks!

-Steven


On Sat, Apr 20, 2013 at 5:25 PM, Michael Klishin <
***@gmail.com> wrote:

>
> 2013/4/21 Steven Degutis <***@gmail.com>
>
>> A friend posted about it on HN at
>> https://news.ycombinator.com/item?id=5582371 (there's no mailing lists
>> for Mac apps afaik)
>>
>
> Steven,
>
> Sounds great! As for the mailing list, feel free to start a Google group
> for your project. It's pretty easy to manage
> and easy to join (many have Google accounts).
> --
> MK
>
> http://github.com/michaelklishin
> http://twitter.com/michaelklishin
>
> --
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to ***@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+***@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+***@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>
>

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Continue reading on narkive:
Loading...