Response to “Literate programming considered harmful”

Post by jcadam » Wed, Aug 31, 2016, 2:00 PM UTC

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…

Post by Jtsummers » Wed, Aug 31, 2016, 2:15 PM UTC

ptero wrote: post #50

Jtsummers wrote: post #43

Earlier quoted context omitted.

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…

  #+NAME: print_hello_world
  #+BEGIN_SRC c
    printf("Hello, World!\n");
  #+END_SRC

  #+BEGIN_SRC c :noweb yes :tangle hello.c
    #include
    int main(int argc, char** argv) {
      >
      return 0;
    }
  #+END_SRC

  * Handling different message types
  #+BEGIN_SRC c :noweb yes
    switch(msg.type) {
      >
      >
      >
     }
  #+END_SRC
  ** Message 101
  Documentation
  #+NAME: msg_101
  #+BEGIN_SRC c
    case 101:
      // handle 101
      break;
  #+END_SRC
  ** Message 102
  Documentation
  #+NAME: msg_102
  #+BEGIN_SRC c
    case 102:
      // handle 102
      break;
  #+END_SRC
  ** Default case
  Documentation
  #+NAME: default
  #+BEGIN_SRC c
    default:
      // handle default
  #+END_SRC

Post by 3pt14159 » Wed, Aug 31, 2016, 2:23 PM UTC

Chris2048 wrote: post #52

3pt14159 wrote: post #25

Earlier quoted context omitted.

Completely disagree. 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. I want a simple for each loop. Where I want comments is where code gets hairy for a reason . For example, extra crafty SQL on some summary metrics page, sure, go ahead and comment that. But I don't w…

> 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?

    # double the counts.
    counts.map! { |count| count *= 2 }

Post by catnaroek » Wed, Aug 31, 2016, 2:35 PM UTC

Jtsummers wrote: post #49

catnaroek wrote: post #41

Earlier quoted context omitted.

> 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…

Post by jcadam » Wed, Aug 31, 2016, 2:51 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…