The need for a classification of documenation artefacts

Today I had a very interesting discussion with my colleague Jarek concerning iDocIt!. During the discussion the question came up whether the interface is the right place for some of the documented characteristics of the operation, e.g. test cases formulated by the tester. I remember that I was confronted with this question in many discussions over the last months.

From my point of view there is a real need for a systematic of

• which places / artefacts exist in a project containing documentation?
• which kind of documentation contents exist?
• which content should be stored in which artefact?

Yet, we don't support such systematic with iDocIt!. I am very interested in the opinion of the you readers on this topic: did you see and use such systematic in your projects?

Avoiding Redundancy in Specifications

I have the impression that some colleagues feel a bit strange in certain situations when specifying in interface. And it is the same with me ;). This feeling comes up, when I formulate something in natural language which is obvious from the corresponding identifiers. But the conventions (e.g. the Javadoc Guidelines) force me to do so. Consider the following example:

/**

 * Returns the customer with the given id or <code>null</code>, if

 * no record is found.

 * 

 * @param id

 *            The id to look for

 * @return The found customer or <code>null</code> 

 */

public Customer findCustomerById(Integer id);

This simple example contains a lot of redundant information:

1. The first part of the introduction sentence (until the conjunction "or") repeats what the identifier of the operation says. 
2. The second part of this sentence tells something, what is also mentioned in the @return-tag.
3. And finally the explanation of the parameter id is also obvious, isn't it ;).

I think, this kind of redundancy is real noise (see Bertrand Meier's great essay "On formalism in Specifications" for further reading). It prevents us from reading the new and important information, in this example the null-behaviour. So, what to do?

To answer this question I would like to know which information should be included in the specification. Then I would assign this information to the different parts of the spec (e.g. the @param-tag). To derive such information, I use the approach of thematic grids which is implemented in iDocIt!. I classify the given operation as a "Searching Operation". The corresponding thematic grid asks me to document the following information:

ACTION: What is done?

OBJECT: What is searched?

SOURCE: Where is searched?

PRIMARY KEY: How is the searched OBJECT identified?

Let's answer these questions:

ACTION: Find the customer with the given id

OBJECT: The customer

SOURCE: The database of our customer relationship management system

PRIMARY KEY: Parameter id

From my point of view, the identifier of the operation explains very well what the operation does. And it also contains the searched OBJECT. I think no further comments are needed. But the Javadoc guidelines force us to formulate an introduction sentence explaining what the operation does. I suggest to explain here, where the operation searches (thematic role SOURCE). From my experience it is always a good idea to explain the null-behaviour only in the @param- and @return-tags. This would lead to this refactored version of the specification:

/**

 * The source of the returned customers is the customer relationship 

 * management system operated by the customer care department.

 * 

 * @param id

 *            Primary Key. <code>null</code> is not permitted here.

 * @return The found customer (object) or <code>null</code> 

 */

public Customer findCustomerById(Integer id);

So, I conclude when specifying an interface one should follow these (rough) steps:

1. Classify the operation and identify which information needs to be documented (e.g. by using the thematic grids of iDocIt!).
2. Fill the thematic grid precisely.
3. Identify which information are already expressed by the identifiers oder could be expressed by identifiers. Strike them from the grid and rename the identifiers, if necessary.
4. Formulate the remaining information as specification, e.g. in Javadoc.

From my experience: for the parameters and return-values there is always the possibility to restrict the set of allowed values. It is also a useful information, if all possible values are allowed (e.g. for an int in Java).

Should I specify every interface?

In many discussions about iDocIt! people raise the question on the added value of specifying every interface (e.g. a Java Interface) in every project? This is a good and reasonable question. 

Personally I made the experience that it is quite helpful to reflect own thoughts, especially when writing software. To be honest, this is my motivation to specify an interface. Such reflections of own thoughts could be done by writing pseudocode on paper, writing unit tests or when specifying an interface in the code. But it costs time and, as we all know, this resource is strictly limited ;).

I think, that interface specification has an added value under one of these conditions:

• The interface provides complex operations and one has to think about them carefully (for reasons see the above paragraph).
• The interface is provided to developers in other organizations (e.g. another project, division or even another company). For two reasons: 

1. The colleague who implemented the interface is not or rarely reachable.
2. To avoid argues ("Who has to catch the null-reference and who pays for it? The implementing company or the invoking one?")

• The system is going to be run a lot of years and one could assume that some colleagues will leave the team or even the company.

Some thoughts on "minor" identifiers

Today I realized something interesting: I wrote a function in Python which should convert a list of booleans into a string with a specific format.The string is used to generate an image visualizing a chart. Because it is a compressed form of the boolean list, I call it "shrinked string". I thought about the identifier of the function and got something like this (in Python syntax)

def convert_to_shrinked_string(boolean_list):

But I was very happy with this because I had the strong feeling that this identifier would be unusual. I can not explain this feeling, it just was there. After some tries I had this idea, which I was quite happy with:

def as_shrinked_string(boolean_list):

I saw this kind of identifiers in the official Java Class Libraries:

Arrays.asList()
Collections.asLifoQueue()

It seems that it is quite useful and common to leave out the verb in some cases. I have seen that in only in cases of "Converting Operations" yet (if you know one other, please tell me via a comment ;)). But, what implications does this have for iDocIt!? iDocIt! extracts its suggestions on aspects to document from the verb of the identifier and won't work without a verb.

On a conceptual layer this is not a problem, because sentences without a verb exist also in linguistics. These sentences are called "minor sentences", e.g. "Great!" or "Yes, please". In these examples the verbs have been omitted due to shortness and convenience. But both sentences could be completed by a subject and a predicate such as "That is great!" or "Yes, please do it". I believe it is the same with the minor identifiers. One could say that "as_shrinked_string(...)" is the short form of "convert_to_shrinked_string(...)" or "get_as_shrinked_string(...)". So, the verb-centric concept of iDocIt! covers this kind of identifiers. But it is not supported in the current version of iDocIt!.