Problem

Using comments to denote code sections feels like subpar solution.

One starts with something like the following:

// workaround for API stupidity
if(result === null) {
  result = [];
}

Then somebody adds another bit so it becomes:

// workaround for API stupidity
if(result === null) {
  result = [];
}
if(result === [1]) {
  foo();
}

Now you are not sure whether the second if is still workaround. You don’t want that. What I usually do in this situation and recommend to others is clearly mark start and end:

// workaround for API stupidity - start
if(result === null) {
  result = [];
}
// workaround for API stupidity - end

if(result === [1]) {
  foo();
}

Now you have duplicated text and subpar programming experience.

Solution

Today (2019-10-21) I have added section syntax (to dev branch) to the language I am working on, Next Generation Shell. I think it solves the problem in a clean way, consistent with syntax and semantics of the language:

section "workaround for API stupidity" {
  if result is Null {
    result = []
  }
}

Or:

result = section "Use algorithm X to calculate blah" {
  a = 1
  b = 2
  a + b
}

In future, for programmer’s convenience backtraces could be augmented with sections’ names.

Update: discussion

1. https://www.reddit.com/r/ProgrammingLanguages/comments/dkzcls/section_syntax_next_generation_shell/
2. https://lobste.rs/s/gert97/section_syntax_next_generation_shell

---

Have a nice week!