In Steve McConnell's excellent Code Complete, he makes a great point about variable names. What he basically says is that if you don't know what to name a variable, you don't really understand how it is to be used. I think this is generally true for all symbol naming conundrums: the name you give a symbol is one of the most important things that you do when programming and tells you a great deal about how robust your design and understanding of the code your are writing is.
At the Foundation we are establishing a practice called Literal Programming. The idea is that (at least theoretically) by following some guidelines regarding creating names for our symbols, we can easily discover when we have the hit the wall on design. We also have another reason, and that is to make code more readable and less reliant on obvious comments. Consider the following line of code: if (this.IsACircle){ That line of code does not need a comment, it reads as natural language. Of course, in VB which uses Me, instead of this, you end up writing code the way Grover from Sesame Street talks. Still, the idea is the same. Construct your symbols such that they read like natural language. That means that we end up shifting the focus from the arguments about simply plural or syntactic naming issues to semantic meanings for our symbols, which is as it should be if we are modeling real world artifacts. And we find that design issues start to revolve around how the things we represent in our code are actually used in the processes we model.
So, our naming conventions start to read more like a grammar than a syntactic convention. We eschew the formatting and notational conventions usually defined in these kinds of posts except to say the following: - Word separation is indicated by the use of a capital letter as in: GroverIsFlying, ThisIsADumbPost, etc,
- Public symbols are denoted by a leading capital letter, all other symbols are denoted by a leading lower case letter. We leave the question of what is “public” vs “private” to be defined distinctly for each language being used.
Beyond that, we attempt to define a grammar based on the natural language requirements of the process being developed/modeled.
- Respect cardinality. If something represents a set, and you use it as a set, use a plural name. Be careful to maintain context to improve readability. For instance, a Row in a table may contain multiple cells, but if you always use it as though it were a black box that is handled singularly, then it is not a plural definition. Always consider context and respect usage.
- Respect verb/noun/adjective agreement. Try to make statements that read like natural language sentences. It is not always possible, but within the constraints of the programming language, you can usually consistently format the code to contain at least the right nouns, verbs and adjectives even if they cannot be maintained in order. In some cases, you can make broad generalaties (recognizing that like natural language, there are exceptions) such as :
- Variables are always Nouns.
- Methods are always Verbs.
- Properties are an interesting case because they are methods masquerading as nouns.
In the next installment of this series, we will take a look at properties in detail and make some decisions about what names make sense and then eventually build the entire grammar out using C#.