I would like to point out the very obvious, that too often gets lost in the shuffle. The code choices we make when designing components act as a series of “signals” that we send to the next developer working on the library or to the developer who is applying and implementing the objects we have created. When we are crafting our code, our choices of class and parameter names, member protection levels, and constructors act as the primary method of disseminating the indented usage of our code.
If an organizations code base is the most inclusive repository of business process knowledge of an organization, then our code libraries supply the nouns, verbs, and adjectives of the business process.
Name for global business understanding
Most business processes have a generally accepted internal name. This is the name that the stakeholder community will call something when telling their business story. Using a different name, as in the statement, “to me blank is this,” when your user community has consolidated on a defined designation, is obfuscation, and to me, smacks of hubris.
Sometimes, you must rename, for elucidation, like when swapping out an acronym or abbreviation for a “Plain English” term that more fully explains the intended usage. But this means you will have to disseminate the new term and usage throughout the hierarchy you are involved in.
One of the best reasons I can think of to develop documentation artifacts before the creation of a code base, is so that you have a more complete set of thoughts on the business processes, so that the names you choose will be indicative of the actual use of your objects in the wild.
Code the meaning of your Intended Usage into your implementations
So lets talk about the following code:
Fig.1
interface iAnimal
{
string Name { get; set; }
object Vocalize(object SpeechType);
}
The Plain English meaning of this code is that all objects that implement iAnimal will have at least one string type property called Name, and a method called Vocalize that takes a parameter of type object and returns an object. By creating an interface (a code pattern that set a base contract of what will be contained in an object) the architect of the code, signals to other human beings implementing his work, that this is the minimal acceptable level of code to implement this functionality. If you implement from this interface, the assembler will only compile your object, if your code object contains all the members specified in the interface. Those the contextual meaning of the code is “you must have all these pieces.”
Fig.2
public class Animal : iAnimal
{
private object _vocalization;
private string _name;
public string Name
{
get { return _name; }
set { _name = value; }
}
public object Vocalize()
{
return _vocalization;
}
}
Figure 2 shows the terms of the code contract being met in full. So we have a cycle of intention and usage, playing out into fulfillment, Contract spelled out by the interface, and then Contractual Obligations met in full by the implementing class.
“What I would like to stress here, is this is not just a series of assembly instructions, this has inherent intended meaning from one human being to another”
So how about when a developer sets up a class as abstract, the Plain English meaning is that the object must be inherited to be used. The compiler will not build if you try to call new on the abstract object. But the contextual meaning that the code’s architect is attempting to send to the implementing developer is that the architect’s intended usage of this code is as a base class that is meant to be inherited.
