I read Simon Parent's thesis, "How Programmers Comment When They Think
Nobody's Watching". Simon is analyzing comments in source files.
Simon quotes two other sources about comments to try to find a
classification scheme. I've quoted the summaries Simon quoted from the
sources [1] and [2]. I've in
On Friday, May 2, 2014 5:39:51 PM UTC-5, Mars0i wrote:
>
> There's a lot in between the amazingly common practice of barely
> commenting code--as if it was self-explanatory--and literate programming.
> Part of the reason I comment my code is so that *I* can understand it
> later.
>
Also, I ful
On 2 May 2014 23:43, Mark Engelberg wrote:
> On the other side, we have people who insist that well-written code never
> needs an explanation, and argue that explanations actively make things
> worse.
Just to be clear, this isn't something I'm arguing for.
- James
--
You received this messag
I find both sides of this argument to be bafflingly extremist.
On one side, we have people who think that literate programming is so
important and so compelling, that the state and ease of the tooling
surrounding it doesn't really matter.
On the other side, we have people who insist that well-wri
There's a lot in between the amazingly common practice of barely commenting
code--as if it was self-explanatory--and literate programming. Part of the
reason I comment my code is so that *I* can understand it later.
--
You received this message because you are subscribed to the Google
Groups "
On 2 May 2014 23:01, u1204 wrote:
> I've attached a piece of code from Clojure, including the terse
> "documentation". I presume one of the early Clojure authors wrote it
> so I assume it is "best case, production code" by Java experts.
>
1. The code you've attached wasn't written by anyone invo
> This is code Clojure programmers depend on to work. Are you suggesting
> that it is easier to read this code than a few paragraphs of natural
> language?
>
> I must say I really find it puzzling that there is so much
> resistance to writing words. It's not that hard.
if the code is so bad that i
James,
> 3. I want to know how the library works internally.
>
> The third use-case is the only time literate programming makes sense, but
> it's also the least used of the three. I'm also not hugely convinced it's
> actually much use - whenever I read literate programs in Clojure I find
> mysel
On 2 May 2014 18:08, wrote:
>
> Writing "just the code" is about as effective as a book containing
> only the physics equations with no text, correct but opaque.
>
A physics equation doesn't completely describe a system. A program does.
Any software designer worth his title would first collect r
On 2 May 2014, at 10:08, d...@axiom-developer.org wrote:
(Just as an aside, there is a conference called "Write the Docs".
see http://writethedocs.org)
The only way to find out is to read the code - that is, the
algorithm,
not just the names. (This code was documented, by the way.) In my
ors the documentation.
This doesn't require a tool, per se, but a good tool would help
others navigate among the ideas.
> Which leads to a larger point: a genuine improvement in the Clojure
> documentation situation requires (IMHO) some Deep Thinking about the nature
> of c
11 matches
Mail list logo
