Response to “Literate programming considered harmful” • Hacker News Board

Re: Response to “Literate programming considered harmful”

#61

Post by Jtsummers » Wed, Aug 31, 2016, 4:54 PM UTC

gavinpc wrote: post #60

Jtsummers wrote: post #58

Earlier quoted context omitted.

What tools did you use for this?

How long do you have? This was for a project called "willshake." The system provides a rough overview of itself [0]. I was using Org for documentation, and I decided to try migrating to a literate codebase. It was clear immediately that I needed a "real" build tool. After some research, I decided that was Tup [1]. Tup is a strict, "functional reactive" build system with extremely fast incremental builds. So I run the…

Thanks for the response. What you've written here seems like the direction I'm trying to explore. However, the corporate proxy server seems to be having trouble with your links (they don't like bitbucket, don't know why), so I'll have to review those after work.

EDIT: Thanks for the tip about tup. That looks like something I could get into. Been reading about it some this afternoon, I'll check it out more tonight or this weekend.

Re: Response to “Literate programming considered harmful”

#62

Post by tome » Wed, Aug 31, 2016, 5:46 PM UTC

catnaroek wrote: post #56

jcadam wrote: post #51

Earlier quoted context omitted.

> If you've used Brainfuck for more than 5 minutes, you already know the entire language. Is it the most readable language ever designed? Oh, come on... BF was specifically/pathologically designed to be unreadable. > Will a cursory read of the source code either tell you how the library deals with corner cases, or convince you that such corner cases don't exist? Um... no, not really (at least not a cursory glance), b…

> Oh, come on... BF was specifically/pathologically designed to be unreadable. I was just exposing a flaw in your “readability” criterion. Another example: you can learn the rules that govern a given cellular automaton in 5 minutes, yet be completely unable to predict what said automaton will do when run. > readability certainly helps track down issues later when you do run into an unforeseen corner case. I'd rather…

> I don't feel confident saying “this code does exactly what I want and nothing else”, because someone might enable an extension I haven't accounted for

If you have any examples of code that, when an extension is enabled, neither fails to compile nor fails to behave in the same way it would be really interested to see them!

If I were to try to conjure some up the first place I would start would be interactions between scoped type variables and typeclasses.

Re: Response to “Literate programming considered harmful”

#63

Post by levelist_com » Wed, Aug 31, 2016, 6:13 PM UTC

jcbeard wrote: post #39

levelist_com wrote: post #37

Earlier quoted context omitted.

Funny enough, I had a C & C++ prof deduct points for comments with the argument that they were redundant and that the code should be self documenting. Then again, this is from a guy who never handed back assignments until the end of the semester and by then couldn't remember why he graded you the way he did. Would just respond with "you didn't understand the material".

that's crap. self documenting code sometimes works...but not always. I love people that hand me HDL and say "it's self documenting." Then you open it, and wire names are "x_1245_to_y." Happened all the time when my students would turn in assignments. That stopped after they realized I graded the documentation too :).

I agree and chose to take the deductions rather than avoid writing comments. By that point I had already been in the industry and I knew better; he has never left academia.

Re: Response to “Literate programming considered harmful”

#64

Post by bunderbunder » Wed, Aug 31, 2016, 7:11 PM UTC

lmm wrote: post #34

quantumhobbit wrote: post #6

The trend in programming lately seems to be less to no comments and less to no documentation; and it is killing the joy I take in programming. Without comments the only way the next guy has a chance to understand the code is if you stick to lowest common denominator patterns and frameworks. You can't do anything that hasn't been done before. I think this is related to the proliferation of frameworks. I can't come up…

> The trend in programming lately seems to be less to no comments and less to no documentation; and it is killing the joy I take in programming. Without comments the only way the next guy has a chance to understand the code is if you stick to lowest common denominator patterns and frameworks. You can't do anything that hasn't been done before. Not true. You just have to express it clearly. I view comments as a code s…

It really, really depends on what the comment is saying.

Comments that explain what the code is doing are usually a travesty. With the possible exception of hairy performance optimizations. Also implementations of algorithms that aren't well known -- oftentimes the original paper is dense, academic and behind a paywall, and the Wikipedia article are a muddled mess. You really owe it to your readers to give a sane and comprehensible explanation instead.

Comments that explain why the code is doing what it does, though, are HUGELY important. There's nothing worse than coming into a legacy codebase and seeing it littered with obvious special cases and workarounds that are all undocumented, so that you have no idea what they're for or whether they're obsolete or not. Skipping these kinds of comments leads to inexorable technical debt, because eventually you'll end up with a codebase where everyone is afraid to change the code.

Re: Response to “Literate programming considered harmful”

#65

Post by Jtsummers » Thu, Sep 01, 2016, 1:02 AM UTC

gavinpc wrote: post #60

Jtsummers wrote: post #58

Earlier quoted context omitted.

What tools did you use for this?

How long do you have? This was for a project called "willshake." The system provides a rough overview of itself [0]. I was using Org for documentation, and I decided to try migrating to a literate codebase. It was clear immediately that I needed a "real" build tool. After some research, I decided that was Tup [1]. Tup is a strict, "functional reactive" build system with extremely fast incremental builds. So I run the…

Finally had a chance to review your various links. That's a very impressive project, I like it quite a bit and have now shared your product (willshake.net) with several friends.

Thanks for the links and the resources. My target with literate programming is a bit different than yours, but you've given me some things to think about. I appreciate that.

Re: Response to “Literate programming considered harmful”

#66

Post by lokedhs » Thu, Sep 01, 2016, 7:27 AM UTC

lumpio- wrote: post #26

Even if it was "harmful" it wouldn't be such a big deal because I for one have never seen an actual program written in literate programming style.

You're in luck. TeX is written in literate style, and its documentation/source is available here: http://brokestream.com/tex-web.html

You can also read Knuths description of the Web system he under to write the code here: http://www.literateprogramming.com/knuthweb.pdf

Re: Response to “Literate programming considered harmful”

#67

Post by gavinpc » Thu, Sep 01, 2016, 2:24 PM UTC

Jtsummers wrote: post #65

gavinpc wrote: post #60

Earlier quoted context omitted.

How long do you have? This was for a project called "willshake." The system provides a rough overview of itself [0]. I was using Org for documentation, and I decided to try migrating to a literate codebase. It was clear immediately that I needed a "real" build tool. After some research, I decided that was Tup [1]. Tup is a strict, "functional reactive" build system with extremely fast incremental builds. So I run the…

Finally had a chance to review your various links. That's a very impressive project, I like it quite a bit and have now shared your product (willshake.net) with several friends. Thanks for the links and the resources. My target with literate programming is a bit different than yours, but you've given me some things to think about. I appreciate that.

Thanks, it makes my day to hear that. I think literate programming was ahead of its time in some ways, including ways that maybe Knuth didn't anticipate. Good luck.

Re: Response to “Literate programming considered harmful”

#68

Post by dllthomas » Thu, Sep 01, 2016, 9:05 PM UTC

3pt14159 wrote: post #55

Chris2048 wrote: post #52

Earlier quoted context omitted.

> I'm not going to summon up simple scarecrow arguments, but for software that makes money, I do not want your clever pattern with comments that saves a microsecond behind a 60 millisecond latency api Is that not a strawman argument?

You are right, that isn't worded the way I intended (not the least because I misremembered the name). I meant to say code examples. For example: # double the counts. counts.map! { |count| count *= 2 } Is the type of strawman I intended to avoid.

I once saw

    using namespace std;  // using namespace standard