Re: How do you name your code blocks?

[Kevin M. Stout]

On 2021-02-15 14:18, Rodrigo Morales wrote:
> 1. Do you use long names?

Usually.  Suppose you were doing a bit of genetic programming.  You might have a
function that computes the next generation from the current one.  You could
write the following snippet that looks suspiciously like pseudocode:

  #+HEADER::noweb-ref genetic/functions
  #+BEGIN_SRC python
  def next_generation(curr):
      <<create a new pool>>
      <<admit the elites>>
      <<perform crossover, admit the offspring>>
      <<perform mutations, admit the mutants>>
      return new
  #+END_SRC

You would then have a block dedicated to each major part of the evolutionary
step.

> 2. If not, how do you name your code blocks to avoid name conflicts?

I have been over the tangling and noweb expansion code quite a bit lately.  The
chief benefit of using #+NAME on a code block is ability to call it.  For
example, you might have

  #+NAME: generate keymap
  #+BEGIN_SRC elisp :var t=keymap
  ...
  #+END_SRC

whose sole purpose is to take a table from elsewhere in an Org file and generate
the code that sets up a keymap.  To use it, you might say

  #+BEGIN_SRC elisp
  <<generate keymap(main keymap)>>
  #+END_SRC

For every other purpose, :noweb-ref works better.  In newer versions of org,
it's the sole means of accumulating code under a common name in the WEB/Noweb
tradition.  In older versions, duplicate #+NAMEs did result in accumulation, but
the behavior was undefined.

A word on syntax: I find 

  #+BEGIN_SRC language :noweb-ref "block name"
  ...
  #+END_SRC

less readable than

  #+HEADER::noweb-ref block name
  #+BEGIN_SRC language
  ...
  #+END_SRC

especially when there are further block-specific header args.  Either is more
cumbersome to type than the #+NAME syntax, but that can be dealt with using
something like

  (add-to-list 'org-structure-template-alist
               '("ss" "#+HEADER::noweb-ref ?\n#+BEGIN_SRC\n\n#+END_SRC"))

Then, to set up a safely-named block, <ss followed by Tab will get you

  #+HEADER::noweb-ref
  #+BEGIN_SRC
  
  #+END_SRC

I hope that helps.

--Kevin M. Stout