Tcl Procs

• Use namespace

  Define your procs with with a namespace like mypackage::foo_proc. Here is a discussion about this. Check many examples in the code, example:

  namespace eval auth {} 
  
  ad_proc -public auth::require_login { 
       {-level ok} 
       {-account_status ok} 
    } { 
       doc...  
       @return something 
       @see ad_script_abort 
    } { 
    ... proc body 
  }
  

• Use procs safely and their safer variations to help keep code robust and avoid security issues.

  Particularly in cases, where user_input is processed, be sure to avoid executing unwanted code. Use the Tcl expand operator {*} instead of eval. Use
      {*}$cmd
  instead of
      eval $cmd
  For legacy code, you might use  util::safe_eval instead of eval in such cases; subst_safe precedes meta characters with backslashes.

• Use named parameters whenever possible 

  Define named parameters on your procs so parameters will not be mixed up if somebody makes a mistake on passing the order of parameters. Also this makes the proc easier to add additional parameters in the future if needed.

  Use:

     ad_proc proc_name { {-parent_id pid} {-child_id cid} } ...

  and not

     ad_proc proc_name {pid cid} ...

  This way developers will need to call proc stating explicitly which parameter are passed. This is especially useful when some parameters are optional.

  Also, when calling a proc in your tcl script, is recommended to write one parameter per line like this:

     set my_var [proc_name  \ 
                      -parent_id $pid \ 
                      -child_id $cid]

  Rather than:

     set my_var [proc_name -parent_id $pid -child_id cid]

  Again, this helps to make the code more clean and readable.



• Use ad_proc to define your Tcl procs

  Make use of ad_proc. And make use of the self documentation facility of ad_proc.

  	ad_proc foo {}
  	   Use this area to document
  	} 
  	   # .... your implementation of proc foo
  	}
  

• This way the API browser will pick up your documentation automatically. Is encouraged to use automatic api-doc documentation that ad_provides, such as: @author, @return, @see

• Avoid using upvar

  Try to avoid using upvar. If needed pass in a parameter that specifies the upvar name. This way the one using your proc has option to name his/her variable. Ex.

      ad_proc upvaring {-upvar_name:required} {
          upvar $upvar_name local_var
      }
  

• Use modern Tcl idioms

  Do not use "==" in comparing strings. Using "if {$string == "foo"}" tries to make a numeric comparison first. Instead make use of "if {"foo" eq $string}" or if you need the negation "if {"foo" ne $string}".
  
  Do not use "if {[lsearch -exact $list $element] > -1}", but use "if {$element in $list}" instead, or "if {$element ni $list}" in case a "not in" test is required.

• Always "Return" at the end of your proc

  And if you have to return more than one variable, use associative arrays, which can be extended by additional fields without breaking code

  So instead of this:

     ad_proc ... {
        ..... 
        return [list $creation_status $creation_message ...]
     } 

  use key/value pairs or Tcl arrays to group related information:

     ad_proc ... {     
        array set creation_info {
                   creation_status {}
                   creation_message {}
                   element_messages {}
                   account_status {}
                   account_message {}              
        } 
        .....     
        return [array get creation_info] 
     } 

• ... or even better: use Tcl dicts

     ad_proc proc ... {} {
  	  set creation_info [dict create  \
  	               creation_status {}   \
  	               creation_message {}  \
  	               element_messages {}  \
  	               account_status {}    \
  	               account_message {}   ]
  	  ....     
        return $creation_info 
    }
  
  

• Read the Tcl Style guide

  This is the Tcl styleguide (PDF), try to apply relevant guidelines. In particular chapter 4,5 and 7