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
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.
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
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 http://blog.stenci.la/chunks-n-funcs/ 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:
It reinforces to the user that a cell is executed like a function with inputs and an output
It allows for code cells with multiple returns (e.g. within a branched
But several early beta users have suggested that an implicit return would be better. Advantages of implicit returns:
More consistent with the behaviour of the console and code notebooks
More consistent with Mini cells
More consistency across external languages (R and several other languages have implicit returns so don’t require you to type
More consistency between
global and the default, locally executed, cells
More consistency with the syntax of cells in a Stencila Sheet
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?