- What Are Conventions For?
- Comments
- Indenting
- Braces and Blocks
- Names and Parts of Speech
- Summary
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Names and Parts of Speech
When you write a part of a program, you are defining new vocabulary. Forth made this explicit. The equivalent of a procedure in Forth is called a word. You write a program by defining new words in terms of existing words. This is true of all programming languages, whether they are procedural, object-oriented, declarative or imperative.
There are two requirements for your code. The first is that a computer should be able to understand it. You can easily check this by compiling it (although it's much harder to check that the computer thinks it means what you think it means). The second requirement is that other humans should be able to understand it.
One of the things that makes the most difference in fulfilling the second objective is defining meaningful names. Compare the following two lines:
array.atIndexPutObject(a, b); array.put(a, b);.
It is a lot clearer in the first what the various parameters are for. Someone reading this line should be able to see that the first parameter is the index and the second is the object to put at that index. In the second example, it's difficult to see which is which.
There are a few things to keep in mind when defining rules for this. The first is to consider the human language in which your programmers will be thinking. If possible, you should try to adopt conventions from that language. German programmers, for example, might use capital letters for all variable names and small letters for function and method names. You should also consider word order in a natural language when defining rules for function and method names.
The final thing that many people overlook is the tools. Most people these days will be using an editor that supports some kind of code completion. This is particularly important when defining rules for enumerated types. Apple's style guidelines here require the type name to be at the start of the value names. For example, imagine you had a type Direction defining left, right, up, and down values. These might be called DirectionLeft, DirectionRight, and so on. When you come to use a function or method that takes a Direction as an argument, you can type Direction (or some part of it) and hit the complete key in your editor. It will then list all of the options for this type.
This produces two more rules for defining coding conventions. One is to think about the tools your programmers will be using. Rules to wrap to a certain width made sense when everyone was using a teletype with at most 80 columns, but make less sense now. If lines of code are too long, they are difficult to read, but these days it might make sense to say lines should be less than 80 characters, not including those used for indent and alignment, rather than forcing an 80-character maximum.
The other rule is that coding guidelines should reduce the amount of time people spend reading the documentation. If you're doing any Cocoa programming, compare the amount of time you spend looking up enumerated type values for things that use the old NeXT convention (with the type name on the end) and the new Apple convention (with the type name at the start). If you're anything like me, you need to look up the NeXT types a lot, but never look up the Apple ones. Less time spent reading documentation means more time spent developing.