Use Unambiguous, Self-Documenting Terminology in Examples

Posted by bob korbus on 29th November 2009

Hello, Android Project SetupThe field names used in this “Hello World” programming example from the Android Developers website could be done better…


As you can see below the 4 different fields to be given values to set up an Android “Hello World” are:

  • Project name: HelloAndroid
  • Application name: Hello, Android
  • Package name: com.example.helloandroid (or your own private namespace)
  • Create Activity: HelloAndroid

(continued below)
Hello, Android Project Setup

Then you are directed to additionally put a line in the Java program code to display “Hello, Android” .

Later in the example, the resulting screen on the Android phone is shown: (continued below)

Hello, Android Screen

See the problem?  The terminology at the top of the window in the title bar is “Hello, Android“.   The text displayed in the main window below is also “Hello, Android”  The obvious question is “Which came from where?”  Is the “Hello, Android” at the top from the Java program code?  Is the “Hello, Android” below the application name that was entered when creating the project?  Are they both from the same setting above or from different settings?  It’s not clear since the exact same terminology was used for 2 different settings.  The person who created the example finds it necessary to disambiguate (big word-wohooo!) for the reader by stating  ‘The “Hello, Android” you see in the grey bar is actually the application title.’

Solution:

Here is a better naming scheme for the example:

  • Project name: HelloAndroidProject
  • Application name: Hello, Android Application
  • Package name: com.example.helloandroidpackage (or your own private namespace)
  • Create Activity: HelloAndroidActivity

and in the Java program code a line was entered to display “Hello_Android_Display_Text

Note that no 2 terms above are the same and the term for each field contains the name of the field itself (at the end in these examples).

Now you get:

Hello_Android_Application Screen

See the difference?  It is now clear that Hello_Android_Application is the application title and Hello_Android_Display_Text is the display text from the program code.

The lesson, then, is to not only use mutually exclusive terminology for distinct fields in any single example, but to go a step further and make the terms self-documenting by putting the field name itself in the term assigned to the field.  Then, anywhere the terms show up in the example it’s unambiguous what they are referring to.

Of course, this philosophy applies to way more than just programming examples.  It applies to ANY example used anywhere to explain anything.  Right?

What do you have to add to this analysis?


11Nov

Comments are closed.