News for hackers. Stuff that matters.
Re:Response to “Literate programming considered harmful” by Jtsummers on Wednesday August 31, 2016 @09:06AM (#12397978)
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” by ptero on Wednesday August 31, 2016 @09:53AM (#12398279)
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.

Re:Response to “Literate programming considered harmful” by Jtsummers on Wednesday August 31, 2016 @10:15AM (#12398437)
NOTE: The plain text mode here doesn't do the org-file content I've included justice. Copy it into emacs and switch to org-mode to see how this'd actually look and work. And I agree, right now I've only figured out how to do this with myself and one or two other people. I use this for both work and side projects. I also tend to work on smaller code teams (max 3 people) so that helps if I want to use this at work on a specific project. You also have to get buy in on the tool (emacs and org-mode, in this case, which is a hard sell these days). I imagine there are ways to make this scale, but I've not figured it out yet. It'll require more tooling and finer-grained access for editing. Merging with this in git could be a pain in the ass with more than a couple people.

You can get code only views, no deletion necessary. Run tangle, which will spit out all the source files (which is part of the compilation/execution step anyways), or use (org-mode specific): C-c C-v C-v (org-babel-expand-src-block). The latter gives you the expanded (this assumes you're using something like noweb[0]) view of the code in a read-only buffer.

Org uses optional noweb notation to include blocks of code in other blocks:

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

  #+BEGIN_SRC c :noweb yes :tangle hello.c
    #include<stdio.h>
    int main(int argc, char** argv) {
      <<print_hello_world>>
      return 0;
    }
  #+END_SRC
<<name>> will be substituted with the contents of the other block. The expand-src-block will give you a view with all substitutions made. C-c C-v C-t (org-babel-tangle) will generate hello.c (could be prefixed with a directory, my preferred way, so it'd be "src/hello.c").

A more useful case than the above, I have a switch/case statement. Each case gets broken into its own source block with documentation around it like:

  * Handling different message types
  #+BEGIN_SRC c :noweb yes
    switch(msg.type) {
      <<msg_101>>
      <<msg_102>>
      <<default>>
     }
  #+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