Guidelines for Good Documentation and Testing


At the top of the program:

On every procedure/function:

On variable, constant, and type declarations in a procedural language

On each conditional or counted loop in a procedural language

For each predicate in a Prolog program:

  • Explain the form and meaning of each argument to the predicate.
  • Explain what it means for the predicate to be true.
  • For each clause defining that predicate, explain how this clause allows Prolog to prove that the left-hand side is true, i.e., explain the right-hand side.
  • % "delete(X, In, Out)" is true iff Out is the list that results from
    % deleting all occurrences of X from In.
    % (Describe each variable)
    % X - an atom
    % In - the list X's are to be removed from
    % Out - the resulting list, after all X's have been removed
    % If In is empty, then the resulting list Out is empty also, no matter
    % what it is that we are deleting.
    delete (X, [], []).
    % If the first thing in the In list is the thing we are deleting, then
    % it should not appear in the Out list.  The Out list is simply what
    % we would get from deleting all occurrences of X from the remainder of
    % the In list.
    % A cut is used here to prevent backtracking to the next delete clause
    % when the front of the In list equals X.  (The next delete clause
    % assumes they are not equal.)
    delete (X, [X|Rest], Out) :- !, delete (X, Rest, Out).
    % We can only get to this clause if the front of the In list is not X,
    % because of the cut in the above clause.
    % In this case, the front of the In list, Y, should appear at the front
    % of the Out list.  The rest of the Out list is what we get from deleting
    % all occurrences of X from the rest of the In list.
    delete (X, [Y|Rest], [Y|Out]) :- delete (X, Rest, Out).
    This may seem like an excessive amount of commenting, but to be complete you should say all of this. (You may be able to express it more concisely, and that would of course be good.) It should not require a great effort to comment this completely if you do understand your code! And it will probably help you debug, as well as help the reader understand.

    On tricky sections of code: