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

Response to “Literate programming considered harmful”

johnwshipman.blogspot.com

Post reply on HN
Print view View original

41–50 of 68 posts

Re: Response to “Literate programming considered harmful”

#41

Post by catnaroek »

jcadam wrote: post #13
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. Enter Golang... a language smaller than even ANSI C. It's readable because…

> It's readable because if you've worked with Golang for more than a week, you basically know every language construct you'll encounter.

If you've used Brainfuck for more than 5 minutes, you already know the entire language. Is it the most readable language ever designed?

> I can usually just go to the source code if I'm trying to figure out how to use a library I just pulled in from clojars.

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?

Re: Response to “Literate programming considered harmful”

#42

Post by falcolas »

Tarrosion wrote: post #40
the8472 wrote: post #32

Earlier quoted context omitted.

> 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. Or - read the tests for that method. - look at the commit log and associated bugs. - use identifiers that are self-explanatory to some extent. auto-complete makes using long names manageable. - step through it with a debugger to see what it does. - use an editor/IDE th…

Many of the techniques you listed are subcategories of reverse engineering. In an ideal world, the code and comments are clear enough that no reverse engineering is necessary. Given a bizarre method, would you rather see a clear comment or spend half an hour stomping through a commit log?

> In an ideal world, the code and comments are clear enough that no reverse engineering is necessary.

In an ideal world, perhaps. But in the real world, the comments contradict the code, the code attempts to use a software pattern which doesn't quite fit (and thus requires a large number of hacks to make it fit), so reverse engineering is your only real choice.

Aiming for an ideal world is never a bad thing, but even if I saw well documented code, I wouldn't trust it. The only difference is that after reverse engineering it anyways, I might feel a bit of surprise when I find that the comments were, indeed, correct.

Re: Response to “Literate programming considered harmful”

#43

Post by Jtsummers »

ptero wrote: post #35
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…

I do not personally see this trend. In fact I see the proliferation of automatic-documenters and automatically checked minimum documentation requirements (which, as is often the case with blanket rules, tends to misfire producing volume but not quality; but this is another topic). It seems literate programming assumes that the person doing development is the same as the one reading documentation. That is not always t…

I haven't figured out literate programming with a large group yet, but I do use it (with org mode) for my own projects (solo or small group). A nice thing, at least with org-mode, is that I can choose whether or not to export a particular bit of content.

  * This headline won't export      :noexport:
    These are some comments for the user and maintainers
    of this document. Describing our formatting and
    practices.
  * This headline will export
    And here's the text describing some message format.
  
    And here's a table showing the layout:
    |  Word  |  12-15  |  8-11  |  4-7  |  0-3  |
    |   0    | WordCnt | TimeTag| ...   |  ...  |
  
    And here's the source for this as a C struct, but
    it's a work in progress. So we won't export it yet.
    #+NAME: MSGXXX_struct
    #+BEGIN_SRC c :exports none
      typedef struct {
        ...
      } MSGXXX_t
    #+END_SRC
No one has to see that stuff until I'm done with it. Or, other tags could be used so I can explicitly select what gets exported depending on the audience. The customer doesn't need the code (at this point). But fellow devs (local, or at partner organizations) may.

Re: Response to “Literate programming considered harmful”

#44

Post by falcolas »

I feel bad to say this, but the practical world has burned me so many times that I simply can't trust anything said after a comment delimiter. If it's not in the code, it doesn't have any impact on what the code is actually doing, making it redundant at best, and misleading at worst.

For that reason, I find myself constantly reverse engineering code. If I am tracking down a bug and run across a bit of obfuscated code which has the comment "optimized hotspot sorting", I'm going to assume that it's wrong. I'm going to take the time to reverse engineer that obfuscated code, to make sure that the code is actually sorting, that it it an actual hotspot, and that it's not the cause of the bug I'm chasing down.

I guess I use it as a negative signal: "the comment says the code does X, I need to verify that it actually does X, correctly". "Optimized" code blocks and comments taken as the truth have pointed me at more bad code than good code.

Re: Response to “Literate programming considered harmful”

#45

Post by panic »

catnaroek wrote: post #33
panic wrote: post #22

Earlier quoted context omitted.

It's ultimately subjective, but I think that code is readable: the variables are well-named and each line says exactly what it does. Abstraction makes it easier for you to think you understand what the code is doing, but if you want to really understand what's going on, you also have to understand how the abstraction is implemented. Straightforward code like this can be understood directly, without having to dig thro…

If you think that code is readable, could you correctly write all pre/post-conditions in between statements?

I think that's a little different. Reading code almost never involves analyzing it to that degree. Usually you're just trying to figure out what part is broken or where you need to add some new functionality.

Re: Response to “Literate programming considered harmful”

#46

Post by catnaroek »

panic wrote: post #45
catnaroek wrote: post #33

Earlier quoted context omitted.

If you think that code is readable, could you correctly write all pre/post-conditions in between statements?

I think that's a little different. Reading code almost never involves analyzing it to that degree. Usually you're just trying to figure out what part is broken or where you need to add some new functionality.

The meaning of an imperative program is given in terms of Hoare triples. If you can't produce such triples on demand, then you don't understand the program in question.

Re: Response to “Literate programming considered harmful”

#47

Post by gavinpc »

I recently ran across this piece, "Literate programming: Knuth is doing it wrong", whose author contends that

> the ends are insufficiently ambitious by focusing on a passive representation [0]

After practicing literate programming seriously for over a year on a large project, I believe that our notion of documents themselves is insufficiently ambitious, for the same reason.

Computer-based media should not be limited to the static forms imposed by paper. It's unfair to critique literate programming per se until we have a truly dynamic mode of representation. (edit, yes, technically we have that now, but it's an order of magnitude more work to create. I'm saying that live, dynamic representations should be our tool for thinking, building, and writing about things in the first place, not after the fact.)

[0] http://akkartik.name/post/literate-programming

Re: Response to “Literate programming considered harmful”

#49

Post by Jtsummers »

catnaroek wrote: post #41
jcadam wrote: post #13

Earlier quoted context omitted.

> 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. Enter Golang... a language smaller than even ANSI C. It's readable because…

> It's readable because if you've worked with Golang for more than a week, you basically know every language construct you'll encounter. If you've used Brainfuck for more than 5 minutes, you already know the entire language. Is it the most readable language ever designed? > I can usually just go to the source code if I'm trying to figure out how to use a library I just pulled in from clojars. Will a cursory read of t…

And the source code doesn't tell you why something was done. Why is this message expected to be only 42 bytes long or less? Is there a specification for it? I can see that someone grabs two adjacent bytes, pulls out 12 bits from them and puts them into a variable called "version":

  version = ((data[0] & 0x0F)
But why? Is this still correct with the current specification of the message format? Who knows! And this is a best case, where "version" is a meaningful variable name.

Re: Response to “Literate programming considered harmful”

#50

Post by ptero »

Jtsummers wrote: post #43
ptero wrote: post #35

Earlier quoted context omitted.

I do not personally see this trend. In fact I see the proliferation of automatic-documenters and automatically checked minimum documentation requirements (which, as is often the case with blanket rules, tends to misfire producing volume but not quality; but this is another topic). It seems literate programming assumes that the person doing development is the same as the one reading documentation. That is not always t…

I haven't figured out literate programming with a large group yet, but I do use it (with org mode) for my own projects (solo or small group). A nice thing, at least with org-mode, is that I can choose whether or not to export a particular bit of content. * This headline won't export :noexport: These are some comments for the user and maintainers of this document. Describing our formatting and practices. * This headli…

That is reasonable for a solo project, which naturally has a common style readable to the author.

In my (maybe skewed) experience though once 2 or more people start adding comments on the same place of code things can get very confusing quickly -- with mishmash of different styles, commented out comments, multiple copy-paste, etc., so the only way to understand what is going on is to delete the whole Kunstkamera and look only at the code.

Post reply on HN