The following are guidelines to the discipline of making sure BOD agents are self-documented:
Document the plan / behavior interface in one program file. As explained earlier, the primitives of the POSH reactive plans must be defined in terms of methods on the behavior objects. For each behavior library, there should be one code file that creates this interface. In my implementations of POSH action selection, each primitive must be wrapped in an object which is either an act or a sense. The code executed when that object is triggered is usually only one or two lines long, typically a method call on some behavior object. I cluster the primitives by the behaviors that support them, and use program comments to make the divisions between behaviors clear.
This is the main documentation for the specification -- it is the only file likely to have both current and intended specifications listed. This is where I list the names of behaviors and primitives determined during decomposition, even before they have been implemented. Intended reactive plans are usually written as scripts (see below.)
Each behavior should have its own program file. Every behavior will be well commented automatically if it is really implemented as an object. One can easily see the state and representations in the class definition. Even in languages that don't require methods to be defined in the class declaration, it is only good style to include all the methods of a class in the same source file with the class definition.
Keep and comment reactive plan scripts. This is the suggestion that requires the most discipline, but having a documented history of the development of an agent can be critical to understanding some of its nuances. Documenting plan scripts effectively documents the history of the agent's development -- it is easy to determine when behaviors were added or modified by seeing what primitives are present in a script. Those who can't remember history are doomed to repeat old mistakes. Keeping a complete set of working scripts documenting stages of the agents development also provides a test suite, useful when major changes are made to behavior libraries.
Script comments should contain: