To return implicitly or explicitly?


Code cells in Stencila Documents usually return an output value (e.g. a number, a plot).

In Mini, Stencila’s simple internal language, the returned value is implicit: if you type 2 * 2 into a cell then the output value is 4.

Code cells in external languages (e.g R, Python) can be declared as global meaning that they are executed within the execution context’s global scope and can assign variables to it. This behaviour is intended to be the same as the behaviour of Jupyter’s code cells or RMarkdown’s code chunks.

For global cells, the output value is also implicit - it’s the value of the last line. So the output value of the following global py() cell would also be 4:

x = 2
x * 2

By default, code cells in external languages are not global and the code is executed within a local scope. This has several advantages, the primary being that the dependency between cells can be better controlled and used to create a reactive document (see for more on this approach).

Because locally executed code cells act like immediately executed functions we decided to use an explicit return. As such, the above cell, without the global keyword would need to be written as:

x = 2
return x * 2

The explicit return has a couple of advantages:

  1. It reinforces to the user that a cell is executed like a function with inputs and an output

  2. It allows for code cells with multiple returns (e.g. within a branched if, else if, else statement)

But several early beta users have suggested that an implicit return would be better. Advantages of implicit returns:

  1. More consistent with the behaviour of the console and code notebooks

  2. More consistent with Mini cells

  3. More consistency across external languages (R and several other languages have implicit returns so don’t require you to type return)

  4. More consistency between global and the default, locally executed, cells

  5. More consistency with the syntax of cells in a Stencila Sheet

  6. Less to type

Some people argue that implicit returns should’t exist in modern languages. But in the context of Stencila Documents, the advantages of implicit returns seem to outweigh the advantages of explicit returns.

So, should we move to implicit returns for external code cells in Stencila Documents?


This seems very useful in theory, but the comments from users imply that in practice it was distracting. It is possible that this would be so different from other notebooks as to be a blocker for use? In the context of a sheet it seems to me that controlling dependencies is key. As implicit returns are common - though perhaps problematic - in modern languages and I’d be curious whether the users who prefer the implicit return are regular Juypter notebooks or R users, rather than Excell users.


The people who have suggest implicit returns would be better have been coders (R, Javascript or Jupyter users) - the very people who might have found explicit returns useful. For, spreadsheet users there is no concept of a return - they just use cell ‘formula’ (i.e. language expressions) - which is essentially what an implicit return is. So, it seems like everyone prefers the implicit return!

We are going to introduce custom functions - so users can define bits of code that they want to reuse in Mini (ie in a document or sheet cell). If someone really wants to have explicit return statements they will be able to write them there.


:thumbsup: This is a good solution!


I also agree. The concept of custom functions is very strong. Implicit returns are more consistent in the other cases.