3 ms·

I do not personally see this trend. In fact I see the proliferation of automatic-documenters and automatically checked minimum documentation requirements (which

by ptero 10y ago

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 the case. And when it is not the case, the code embedded in documentation can hurt readability. For example, I try to get all interface specs distributed, discussed and confirmed ASAP, usually WAY before the code is mature enough to be shown outside. Also, getting others to read, think about and comment on even short ICDs is difficult as is. Getting them to read early ICDs interspersed with early code? Not going to fly. My 2c.

Jtsummers 10y ago
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.
- ptero 10y ago
  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.
  - Jtsummers 10y ago
    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

by ptero 10y ago

Jtsummers 10y ago

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.

ptero 10y ago
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.
- Jtsummers 10y ago
  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