News for hackers. Stuff that matters.
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

There are no comments on this comment yet.