Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Literate programming is much more than just commenting code

justinmeiners.github.io

Post reply on HN
Print view View original

61–70 of 112 posts

Re: Literate programming is much more than just commenting code

#61

Post by taeric »

QuikAccount wrote: post #7

I like literate programming in theory but the most common response I see to it is that writing self documenting code is better because as you are working on a code base with many people, it is unlikely they will keep your prose up to date as the code is changed.

The problem with self documenting code is that it doesn't help justify all of the parts into the whole. This is particularly troublesome in code where a refactor effectively isolated entire sections of the code, but the person that did the refactor didn't realize it, and now you have code that exists only for the sake of existing tests.

Re: Literate programming is much more than just commenting code

#63

Post by taeric »

copperx wrote: post #2

It would be great if IDEs supported literate programming; the tangle/weave commands, simple as they are, create many possible points for navigation. An IDE would be ideal to go back and forth from the prose to the code.

You will be shocked to know that emacs and org-mode can do exactly this. You can tangle source, and go from the tangled source back to the section that generated that source.

If you are wanting to just do cweb, then the debugging symbols already let you step through the source line by line without having to look at the tangled source.

Re: Literate programming is much more than just commenting code

#64

Post by ggm »

tomjen3 wrote: post #58
ggm wrote: post #30

I have always felt a literate program is probably for many of us, a future deliverable on the hack we've implemented up front. Very very few people can start from the abstraction and get TO a literate outcome without a lot of false steps along the way. Or, as an alternative, the LOC of a literate program has to include the 100x cost of exploring how to carve it out of the block of mud we start from, including making…

>Very very few people can start from the abstraction and get TO a literate outcome without a lot of false steps along the way. But don't writers face the same issue with their text? Am I the only one who writes more code than what ends up in a PR? Isn't that exactly what the Git history is for?

Sure. So how many published works do we ever see the git logs for? Significant literary works, one or two per author, pre digital era. Galley proofs, or Marcel Prousts chaotic revisions which G Scott Moncrieff fought with doing his translation, and then Terence Gilmartin. Dickens, some of them. Most writing? Never seen.

Re: Literate programming is much more than just commenting code

#65

Post by mci »

IMHO, attempts to show literate programming on screen are doomed to meet with mediocre success. DEK invented literate programming with printed books in mind. I dare say that the only successful literate programs are books printed on paper.

First, in a printed book, it is easier to find a previous page and compare a fragment on it with the current fragment. Second, a printed book has no links tempting you with the words "CLICK ME" to disrupt the flow so you can read it from cover to cover with fewer distractions. Third, anecdotally, I can see flaws much easier on a printout than on screen, both in programs and in texts.

Re: Literate programming is much more than just commenting code

#66

Post by shakna »

throwaquestion5 wrote: post #36
BeetleB wrote: post #11

The problems one will run into with literate programming: 1. Lack of tooling. 2. Refactoring becomes nontrivial 3. How one would write a program in literate style will vary widely from person to person. If you write your code in literate style, it may be easy for you to follow it years later and modify it, but it likely will not be the case for a coworker. If they have to modify the code, the cognitive load will not…

Problems 1 and 3 I could imagine. I would need to learn how to be a better writer to share a literate program. As someone experienced in the topic, What's the biggest hurdle when trying to refactor the code?

Refactoring becomes the dual problem space of both programming and editing.

It's simply more work - but that "more work" is vitally important, tedious, and resistant to any kind of automated help.

Re: Literate programming is much more than just commenting code

#67

Post by eterevsky »

I tried reading some literate code, and I have troubles understanding it, compared to well structured normal code with moderate amount of comments.

Sometimes when you are writing an article it may make sense to write LP-like snippets of code like

    int my_function() {
      // Initialize variables
      return 0;
    }
but you don't really need to invent the whole "literate programming" concept to do this and you don't need to write all of your code like that.

Re: Literate programming is much more than just commenting code

#68

Post by t0suj4 »

taeric wrote: post #61
QuikAccount wrote: post #7

I like literate programming in theory but the most common response I see to it is that writing self documenting code is better because as you are working on a code base with many people, it is unlikely they will keep your prose up to date as the code is changed.

The problem with self documenting code is that it doesn't help justify all of the parts into the whole. This is particularly troublesome in code where a refactor effectively isolated entire sections of the code, but the person that did the refactor didn't realize it, and now you have code that exists only for the sake of existing tests.

I interpret self documenting as writing the what in the code and writing comments about the why. While minimizing the places where you need to explain your code.

My role of thumb is that if it's not obvious why that particular line is there and removing it would break functionality, add a comment.

Re: Literate programming is much more than just commenting code

#69

Post by andrewshadura »

ifupdown, the Debian tool to manage network interfaces, used to be written in literate C using noweb. When I took it over from the original author, I struggled to understand how it worked. I had to print out the weaved version of it, and read it making notes on the paper. I eventually managed to make sense of it, but making any change was very difficult, so I ended up converting it to plain C, adding some comments from the original literate source and reindenting.

Re: Literate programming is much more than just commenting code

#70

Post by kwhitefoot »

mci wrote: post #65

IMHO, attempts to show literate programming on screen are doomed to meet with mediocre success. DEK invented literate programming with printed books in mind. I dare say that the only successful literate programs are books printed on paper. First, in a printed book, it is easier to find a previous page and compare a fragment on it with the current fragment. Second, a printed book has no links tempting you with the wor…

> in a printed book, it is easier to find a previous page and compare a fragment on it with the current fragment.

This is why I like plain text for everything (or Emacs Org Mode) because then I can have multiple frames showing different parts of the same buffer in Emacs.

Post reply on HN