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

Have a nice week!