7B Software Programmer's Style Guide

I sometimes refer to this concept as The Program Who Knew Too Much. We want to avoid writing a routine whose correct operation depends upon intimate knowledge of a different routine.

It is probably not an exaggeration to say much of what we refer to as "software refactoring" actually refers to removing duplications in program logic, thus effectively "factoring" a shared concept into a single routine.

This rule is important, but it is not necessary to follow it slavishly. There are some places where insisting on a SPOT is going overboard. A good example of this is the Tcl/Tk widget name. It is usually OK to refer to a Tcl/Tk widget by name (for example: .dialog.listbox) throughout the program, rather than referring to the name by some variable abstraction. In theory, this is a duplication; in practice, creating variables to hold widget names is usually not worth the effort, and the cure of variable namespace pollution is worse than the disease of duplication.

Many ideas for doing "programming in the large" came out of this period of time. Included in these ideas were: Egoless Programming, Object Oriented Programming, Institutionalized Feedback Loops and Reviews, Best Current Practices, Integrated Development Environments, and some others that I've probably forgotten.

The lesson from looking back on this time was that none of these ideas actually yield better software.

Instead, experience shows that the way to create the best software is by following these guidelines:

• Hire highly talented programmers.
• Have them program in languages that let them express design ideas as directly as possible.
• Avoid single points of failure in the programming process.
• Choose tracking and change management tools that are enjoyable for the programmers to use.

That last item sounds as if it might be an endorsement of the Integrated Development Environment, but in fact it's just the opposite. I have yet to see an IDE that allows the programmer to change and keep track of software; instead, the IDE itself keeps track. If you're the programmer, that means that you have to keep track of both the program and the IDE in order to have any confidence that what you're writing is in fact what is being generated.

The takeaway from all of this is: To write excellent software, the programmer must be in control at all times.

The whole concept of style is difficult to deal with because of several factors, the most important of which is probably programmer autonomy. After all, if the right philosophy is to create an environment where the programmer is in control, then how is it that any technique mandating an issue of pure style is defensible?

There are three reasons why pure style issues should be fair game for a Guide such as this.

1. Some styles just look better than other ones.
2. A set of programs with differing styles cause the program reader to be hopelessly distracted by style issues rather than issues of more substance.
3. By dealing with style directly, we generate a market for better and better styles. In other words, we can't improve what we don't even talk about.

Some pure style issues that are described later in this Guide are rather arbitrary. (The indentation and comment styles are good examples of this.) We like the styles promoted here, but we realize there may well be other styles that are equally defensible. I can come up with reasons why, for instance, a 2-space indentation style is "better" than a 4-space one; but you might reasonably disagree. Things like this basically come down to uniformity: We've picked a style, so let's stay with it.

Example: file porridge.tcl can have at most one namespace, and the namespace's name is porridge.

Rule. The file should contain some summary comment information at the top describing the goal of the namespace.

Example: in file porridge.tcl:

# This module provides methods to change the temperature of the porridge, and
# to check its current temperature.
#
namespace eval porridge {
  ...
}

3.2 Namespaces.

Rule. Use namespace variables rather than global variables.

Rule. If a namespace variable is referenced by another source file, then the namespace variable should be defined at the top of the file. The namespace variable definition should have a useful comment (see Comments section below).

Example:

namespace eval porridge {
  variable gval ;# The Goldilox setting of the porridge.  May be one of:
                ;#   "too hot", "too cold", "just right"

  ...
}

3.3 Procedure Naming Conventions.

Example:

# This proc will make the porridge warmer by $deg degrees.
#
proc warmup {deg} {
  ...
}

don't do this:

# This proc will make the porridge warmer by $deg degrees.
#
proc makePorridgeWarmerBy {deg} {
  ...
}

Rule. If the Tcl procedure is called from outside of the file, its name should start with an alpha character (a-z). If it is only referenced internally within the file, its name should start with an underscore (_). Organize the procedures so that all of the externally callable ones are at the top of the file and all of the "for internal use only" ones are at the bottom. And add a comment where the demarcation point is, between the external and internal procs.

Example: In this example, ::porridge::warmup is callable from outside the module and ::porridge::_too_hot is only called from within the module.

namespace eval porridge {
  ...

proc warmup {deg} {
  ...
  if {[_too_hot $deg]} {error "fire hazard"}
}

...

#
# All procedures below this point are for the internal use of this
# module only.  Do not call them from outside this module.
#

# This proc returns TRUE if the porridge temperature in $deg
# is hot enough to set fire to the house.
#
proc _too_hot {deg} {
  return [expr {$deg>5000}]
}

}

3.4 Indentation.

Example:

proc warmup {deg} {
  ...
  if {[_see_a_bear]} {
    _call_911
    _find_pistol
  } elseif {[_see_a_rabbit]} {
    _marvel_at_tail
  } else {
    _check_stove
  }
  ...
}

Rule. Add 4 spaces for line continuations. Avoid lines that are more than 80 characters.

Example:

proc _call_911 {} {
  if {[catch {set pcall [::phone::call 911]} msg]} {
    tk_messageBox -icon info type ok -message \
        "Oh my.  911 service is out in the Hundred Acre Wood.  Perhaps you\
        should consider finding your pistol."
    return
  }
  ...
}

Rule. Procedures start at the beginning of the line. Don't indent the procedure, even though it's in a namespace. (All of the above examples use that convention.)

To make this work, you should design your module such that all of the module's namespace variables are initialized once, when the program starts up, and not each time the module is sourced.

Example:

namespace eval porridge {
  variable gval ;# The Goldilox setting of the porridge.  May be one of:
                ;#   "too hot", "too cold", "just right"
  ...

# This proc is called exactly once, when the program first starts up
#
proc init {} {
  set ::porridge::gval "just right"
}

}

Don't do this: This will cause the ::porridge::hot variable to be reset to "just right" each time the module is sourced.

namespace eval porridge {
  variable gval {just right} ;# The Goldilox setting of the porridge.  May be 
                             ;# one of: "too hot", "too cold", "just right"
}

3.6 Comments.

Rule. A comment should be indented on the same level as the code it's commenting on. The comment's form should be:

• a blank line, followed by
• the comment lines, followed by
• an empty comment line.

# This proc will return TRUE if goldilocks is tired
#
proc is_tired {} {
  return {expr [_insulin_kicking_in $::porridge::_last_eaten]}
}

The comment form is to be followed both for comments for procedures (as in the above example) and for comments within procedure bodies.

Let's move on to the problem of when to comment. There are two basic types of comments:

1. Comments that describe something (the "what"): Description comments.
2. Comments that explain something (the "why"): Explanatory comments.

Rule. Description comments should be kept to a minimum.

Description comments are useful in describing large swaths of code, or for describing variables that are effectively global in scope. So for that reason, all namespaces should have a descriptive comment, and all namespace variables that are referenced external to the module should have a descriptive comment. And most procedures should have a descriptive "prologue comment" as well.

Conversely, most procedure bodies should not have any description comments. The exception to this is a procedure body that is (necessarily) too long for a programmer to be able to quickly understand a subpart of the procedure body at a glance.

If you feel the need to add a description comment within a procedure body, you should ask yourself if the procedure needs to be split into two or more procedures, or whether it is unnecessarily long, or whether it should be rewritten entirely.

Rule. Explanatory comments should be used whenever it is likely that a programmer will wonder why something is being done.

This type of comment is used when some clever programming trick accomplishes a task, or when some unapparent edge case is being handled.

Example. This example provides examples of both description comments (namespace, namespace variable, and procedure) as well as an explanation comment in the _see_a_bear procedure.

# This module provides methods to change the temperature of the porridge, and
# to check its current temperature.
#
namespace eval porridge {
  variable gval {just right} ;# The Goldilox setting of the porridge.  May be 
                             ;# one of: "too hot", "too cold", "just right"

# This proc is called exactly once, when the program first starts up
#
proc init {} {
  set ::porridge::gval "just right"
}

# This proc will make the porridge warmer by $deg degrees.
# It will also look outside to check on wildlife.
#
proc warmup {deg} {
  ...
  if {[_see_a_bear]} {
    _call_911
    _find_pistol
  } elseif {[_see_a_rabbit]} {
    _marvel_at_tail
  } else {
    _check_stove
  }
  ...
}

#
# All procedures below this point are for the internal use of this
# module only.  Do not call them from outside this module.
#

# This proc returns TRUE if a bear is seen outside.
#
proc _see_a_bear {} [
  set things_seen [_look_outside]
  set bears [_get_bears $things_seen]
  set any_bears 0
  if {[[llength $bears]>0} {

     # Check for the case where it's a teddy bear.  Watch out for the
     # case where it's a very small but very alive cub.
     #
     foreach bear $bears {
       if {[_tiny $bear] && [_not_moving $bear] && [_not sleeping $bear]} {
         continue
       }
       set any_bears 1
       break
     }
  }
  return $any_bears
}

proc _call_911 {} {
  if {[catch {set pcall [::phone::call 911]} msg]} {
    tk_messageBox -icon info type ok -message \
        "Oh my.  911 service is out in the Hundred Acre Wood.  Perhaps you\
        should consider finding your pistol."
    return
  }
  ...
}
}

In the _see_a_bear procedure, there is a brief description comment that describes the procedure, and there is a brief explanation comment that makes it clear why the code is checking for small bears that are neither moving nor sleeping. The assumption is that it would have been difficult for the programmer to figure out the motivation behind doing that check without such an explanation.

3.7.1 The "expr" and "if" commands.

This goes for if-expressions as well!

Example.

...
proc warmup {deg} {
  ...
  if {![_turn_on_stove]} return
  _wait 5 ;# Will finish after waiting 5 minutes

  # Allow for some loss of heat
  #
  set deg [expr {[_current_stove_temperature]*.90}]
  ...
}

3.7.2 The "regexp" command.

Example:

proc _whichbear {bear} {
  if {[regexp {mama bear: (.*)} $bear -> name]} {
    return "mama bear's name is $name"
  }
  ...
}

3.8 Boolean or enumerated parameters.

Example:

proc _goldi_in_house {{chairstate -notbroken} {bedstate -nosleeper}} {
  return [expr {$chairstate!="-notbroken" || $bedstate!="-nosleeper"}]
}

  if {[chair_in_2_pieces]} {set chstate -broken} {set chstate -notbroken}
  if {[_goldi_in_house $chstate -nosleeper]} {
    puts "Someone's in this house"
  }

  set chstate [expr {![chair_in_2_pieces]}]
  if [[_goldi_in_house $chstate 0]} {
    puts "Someone's in this house"
  }

3.9 Debug Output.

The reason for this is twofold:

1. You don't have to. Tcl is powerful enough so that you can add debug statements on the fly at runtime if you have to deal with a bug at a remote site or on a test machine.
2. You should write a more thorough introspection GUI module if your program is sufficiently complex.

A very good example of a typical use is when the program must open a connection to a socket service. The program has to open the socket, wait for the socket to have data on it before reading it, wait for the socket to become writable before writing it, and handle the case where the remote server terminates the connection.

Plus, usually there is other housekeeping associated with the socket having to do with the service that is actually being provided by the connection.

The best way to handle this in Tcl is to create a namespace variable whose name is generated on the fly from the (unique) socket identifier.

Example:

namespace eval porridge {
...

# Place a call to grandma.  She's on x2525 at www.grandma.com
#
proc talk_with_grandma {} {
  if {[catch {socket www.grandma.com 2525} fd]} {
    tk_messageBox -icon error -type ok -message "No grandma: $fd"
    return
  }
  upvar #0 ::porridge::_grandma_$fd V 
  set V(state) quiet
  fileevent $fd readable [list ::porridge::_handle_grandma $fd]
}

# Handle a message from grandma
#
proc _handle_grandma {fd} {
  upvar #0 ::porridge::_grandma_$fd V
  if {[eof $fd]} {
    tk_messageBox -icon info -type ok -message "Grandma no longer talking"
    unset V
    close $fd
    return
  }
  if {[catch {read $fd} buf} {
    tk_messageBox -icon error -type ok -message "Grandma phone failed: $buf"
    unset V
    close $fd
    return
  }
  switch $V(state) {
    quiet {
      if {[regexp {Hello} $buf]} {set V(state) greeted}
      puts $fd "Hi, grandma"
      flush $fd
    }
    default {
      if {[regexp {Goodbye} $buf]} {set V(state) finished}
    }
  }
  if {$V(state)=="finished"} {
    puts $fd "Bye, grandma"
    unset V
    close $fd
  }

}

}

Watch out: Socket names are reused by Tcl. So if you close a socket and then open a new socket, it is quite likely that the new socket's name will be the same as the old one. So be careful to clean up when closing a socket! (Such cleanup is also required to avoid leaking memory, which would not cause the same behavior that accidental reuse of a name would, but which could cause serious problems in a long-running application.)

5.0 Conclusion

If you hate something in this guide, please let me know. We'll figure something out. (If you hate the idea of this guide, I'm not sure I can help though.)