style guide: return

1 files changed, 13 insertions, 0 deletions

diff --git a/docs/tcl.md b/docs/tcl.md
index 234e5e63..0bcea651 100644
--- a/docs/tcl.md
+++ b/docs/tcl.md
@@ -58,6 +58,19 @@ subfolder) or printed programs.
 Use `try` (and `on error`) in new code. Avoid using `catch`; it's
 older and easier to get wrong.
 
+#### Return
+
+In general, don't use `return` if it's the last statement in a code
+block. Just put the statement there whose value you want to return.
+
+Bad: `proc add {a b} { return [expr {$a + $b}] }`
+Good: `proc add {a b} { expr {$a + $b} }`
+
+Bad: `set x 3; return $x`
+Good: `set x 3; set x`
+
+You should use `return` only when you actually need to return _early_.
+
 #### Tcl datatypes
 
 Create a namespace for your datatype that is an ensemble command with