How do you name your code blocks?

How do you name your code blocks?

[Rodrigo Morales]

I think this question is aimed to people which have Org Mode files
with a lot of source code blocks and those code blocks are usually
assigned a name.

I am asking this question because I just noticed that it is not
possible to have multiple source code blocks with the same name. If
that occurs, then

1. The first code block found with the given name is only taken into
   consideration
2. =M-x org-lint= warns about that.

So, taking into consideration that that is not allowed, I have the
following questions for you

1. Do you use long names? That is, instead of using =generate-table=,
   which is ambiguous, you would use
   =generate-table-grocery-shopping-2020-may=. Another example:
   instead of using =create-venv= you would use
   =create-venv-for-personal-blog-in-home=.

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

-- 
Greetings,
Rodrigo Morales.

IRC: rdrg109 (freenode)

Re: How do you name your code blocks?

[Greg Minshall]

Rodrigo,

i guess part of the answer depends on why you are naming your code
blocks.  for me, the main reason is for <<noweb>>.  another is so that
when org-mode asks me if it should run a block, it has a name to tell me
to help in my decision-making.

for <<noweb>>, there is noweb-ref header argument (see manual).  i don't
know if that might be of help.  it allows you to name a group of source
blocks, intended to be treated as a group.

using noweb-ref, one can also name a bunch of to-be-concatenated code
blocks as a property of a (super-) node in the tree:
----
       :PROPERTIES:
       :header-args+: :tangle build/package/covid.19.data/R/aggregate.R
       :header-args+: :noweb-ref aggregates
       :END:
----
(that sets all otherwise-un-attributed code blocks in that node, or any
sub-node, in the tree to tangle to the .R file, and to be "embeddable"
in other code via, e.g., things like this:
----
   <<coplot>>
   <<colean>>
   <<duration>>
   <<aggregates>>
   <<dailies>>
----
)

hope that helps.

cheers, Greg

Re: How do you name your code blocks?

[Rodrigo Morales]

Greg Minshall <minshall@umich.edu> writes:

> i guess part of the answer depends on why you are naming your code
> blocks.

I was asking because in my notes in Org Mode, I am used to create
subheadings for each question I have. Here's an example:

Let's say that in my notes on Python, I have the following content

#+begin_src org
,* DONE How to get the number of lines in a file?
  - State "DONE"       from              [2021-02-16 Tue 20:02]

,#+NAME: create-file
,#+begin_src dash :results silent
cat << EOF > main.txt
first
second
third
EOF
,#+end_src

,#+begin_src python
print(len(open('main.txt').readlines()))o3
,#+end_src

,#+RESULTS:
,#+begin_example
3
,#+end_example

,* DONE How to print most repeated word in a file?
  - State "DONE"       from              [2021-02-16 Tue 20:02]

,#+NAME: create-file
,#+begin_src dash :results silent
cat << EOF > main.txt
fizz fizz fizz
buzz buzz buzz buzz
foo
bar bar
EOF
,#+end_src

,#+begin_src python
import re
from collections import Counter

with open('main.txt') as f:
    passage = f.read()

words = re.findall(r'\w+', passage)

word_counts = Counter(words)

print(word_counts.most_common(1))
,#+end_src

,#+RESULTS:
,#+begin_example
[('buzz', 4)]
,#+end_example
#+end_src

As you can see above, there are two code blocks which creates two text
files so that a Python script can then process it. Both of them create
a text file, that's why I have used =create-file= as the name of those
code block. I could have used very long names but I don't find
comfortable myself doing that since it adds extra effort to think in a
name for such simple code blocks (see below an example of the approach
of using long names).

#+begin_src org
,* DONE How to get the number of lines in a file?

,#+NAME: create-file-for-counting-lines
,#+begin_src dash :results silent
cat << EOF > main.txt
first
second
third
EOF
,#+end_src

,* DONE How to print most repeated word in a file?

,#+NAME: create-file-for-finding-most-repeated-word
,#+begin_src dash :results silent
cat << EOF > main.txt
fizz fizz fizz
buzz buzz buzz buzz
foo
bar bar
EOF
,#+end_src
#+end_src

-- 
Rodrigo Morales.
IRC: rdrg109 (freenode)

Re: How do you name your code blocks?

[Eric S Fraga]

On Monday, 15 Feb 2021 at 14:18, Rodrigo Morales wrote:
> 1. Do you use long names? 

Yes.  Fully qualified and detailed.  And then rely on completion to jump
to code blocks (using org-babel-goto-named-src-block).

-- 
: Eric S Fraga via Emacs 28.0.50, Org release_9.4.4-213-g49364f

Re: How do you name your code blocks?

[Rodrigo Morales]

Eric S Fraga <e.fraga@ucl.ac.uk> writes:

> Yes.  Fully qualified and detailed.  And then rely on completion to jump
> to code blocks (using org-babel-goto-named-src-block).

Thanks for the answer. I didn't know about
=org-babel-goto-named-src-block=.

Regarding using fully qualified and detailed names: I feel like it is
not a good idea for the use case I have with Org Mode. I have multiple
big Org files for each programming languages I've used and while using
long names might avoid name conflicts, there would be a time in which a
name conflict would occur because it is necessary to avoid using a name
which has already been used, so for example if I name a code block with
=generate-data-for-plotting=, I can't use that same name again.

For this reason, I was thinking in the following workaround: use use the
ID of the subtree as the prefix of the name of the code blocks. Thus,
name conflicts are less likely to occur (see example below).

#+begin_src org
,* DONE How to get the number of lines in a file?
  :PROPERTIES:
  :ID:       ec1f7066-213c-458e-a0f9-786b722218f4
  :END:

,#+NAME: ec1f7066-213c-458e-a0f9-786b722218f4/create-file
,#+begin_src dash :results silent
cat << EOF > main.txt
first
second
third
EOF
,#+end_src

,* DONE How to print most repeated word in a file?
  :PROPERTIES:
  :ID:       e0768c19-080f-47db-9dc2-3bd00efdd036
  :END:

,#+NAME: e0768c19-080f-47db-9dc2-3bd00efdd036/create-file
,#+begin_src dash :results silent
cat << EOF > main.txt
fizz fizz fizz
buzz buzz buzz buzz
foo
bar bar
EOF
,#+end_src
#+end_src

As we can see above, both =dash= code blocks are given the name
=create-file= because both of them create a file but the ID of the
heading is used a the prefix in order to avoid a name conflict.

Let me know your thoughts on this workaround :)
-- 
Rodrigo Morales.
IRC: rdrg109 (freenode)

Re: How do you name your code blocks?

[Greg Minshall]

hi, Rodrigo,

thanks.  i understand.  we all like "int i;" to be independent in
separate functions (as it were).  right now, names of source blocks are
global to the .org file, and i don't suspect that will (or should)
change.

i apologize for bringing it up, but the one thing that jumps out at the
programmer part of me is that the python blocks in your code don't
"know" what main.txt actually contains when they are executed, as there
is no dependency on the correct "create-file" source block.  possibly,
though, if you created some dummy :var (on the python "begin_src" lines)
to express this dependency, it would help?  or, maybe it doesn't really
matter?

cheers, Greg

Re: How do you name your code blocks?

[Rodrigo Morales]

Greg Minshall <minshall@umich.edu> writes:

> Right now, names of source blocks are global to the .org file, and i
> don't suspect that will (or should) change.

Yep, I understand that. I explained a workaround for using short names
for code blocks and avoid name conflicts in
[[https://lists.gnu.org/archive/html/emacs-orgmode/2021-02/msg00281.html][this
answer]].

Greg Minshall <minshall@umich.edu> writes:

> i apologize for bringing it up, but the one thing that jumps out at the
> programmer part of me is that the python blocks in your code don't
> "know" what main.txt actually contains when they are executed, as there
> is no dependency on the correct "create-file" source block.  possibly,
> though, if you created some dummy :var (on the python "begin_src" lines)
> to express this dependency, it would help?  or, maybe it doesn't really
> matter?

I understand your point. I am currently expressing that dependency by
putting a =#+CALL= statement with =:results silent= above the Python
code block. However, doing that doesn't really express a dependency
because I need to execute the =#+CALL= statement first and then the
Python code block. It would be nice if we could associate a code block
(B) to another code block (A) so that (B) is execute before (A) is
executed. I created
[[https://lists.gnu.org/archive/html/emacs-orgmode/2021-02/msg00245.html][this
thread]] in the mailing list asking this. One of the solutions mentioned
in that thread is to use the =:var= header argument which you mentioned
and works great.

From now on, I will be using the ID of the current subtreeas the suffix
(not prefix) of code block names so that name conflicts doesn't occur
between different subtrees and will express dependency between code
blocks by using the =:var= header argument.

Perhaps, having a =:pre= header argument, just as the =:post= header
argument exist, would help expressing depdency between code blocks in a
clearer way. I consider the =:var= header argument a hacky way to
associate two code blocks.

-- 
Rodrigo Morales.

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

Re: How do you name your code blocks?

[Eric S Fraga]

TIL: you can have spaces in src block names!

Thank you!

-- 
: Professor Eric S Fraga
: Visit useplaintext.email & www.ucl.ac.uk/~ucecesf/
: Consider meet.jit.si and bigbluebutton.org for video conferencing
: PGP/GnuPG key: 8F5C 279D 3907 E14A 5C29  570D C891 93D8 FFFC F67D