The code is not the documentation!

There are a lot of reason why the code can’t be the documentation.  The first reason is obvious because most organizations and individuals have no standards in place.  As an example let’s compare sheet music with coding – shall we.

Keep in mind sheet music was not always been what it is today.  There have been several evolutions of what is known as sheet music.   A Benedictine Monk named Guido of Arezzo was the first to attempt the standardization of music notation in his book Micrologus published in 1026. The idea of sheet music has evolved over several centuries and as software evolves standardization of terms, vocabulary and symbols will be commonplace.  I hope it does not take the software industry a 1,000 plus years to standardize terminology.

There is no accepted standard for notation for software development.   By notation I mean how do we communicate about software.   Notation differs from organization to organization and even differs within an organization.    The lack of consistent standardized vocabulary, verb usage, and symbols is really unique to software development.

Any first year music student, unlike software developers, learns the symbols of music and basic music notation.  Music notation is a system of writing music so that specific pitches and rhythms can be communicated.  Music notation indicates exact pitches by the upward or downward placement of symbols called notes on a staff.  A note is an oval.  Its duration is indicated by whether it is black or white and if it has a stem and flag.  As music students progress the symbols become more complex.  While most music novices can play and understand a level one music book, it is impossible for a novice to play or even understand an advanced music composition.

Sheet music, unlike code or software documentation, is written concise and consistently. Structure in music allows the composer to communicate to musicians how the piece should be played.  It is a printed page, like a book or poem, that tells a story.  A talented, creative and imaginative person created the story.  Without consistently written sheet music it would be impossible for musicians to play the story with their instrument.   Just like structure does not inhibit the creativity of a composer, structure does not inhibit the creativity of a software developer.

Sheet music transcends language and time. Music notation gave western music a means of a written historical record.   I was working in Vienna, Austria and picked up some sheet music written by Wolfgang Amadeus Mozart  for my daughter who plays the piano.    Mozart’s lived 250 years ago and his language was German.  My daughter who is 15 years old does not speak German, but can pick up this sheet music and play it on her piano.  While the content is different the symbols are exactly the same for a contemporary piece like Linus and Lucy, the recognized Charlie Brown theme song written by Vince Guaraldi.   The same could apply to two different software functional specifications, they should be written in a consistent manner.  I do not expect a software documentation to transcend 300 years, but it should transcend the entire life of the software application.

There is nothing on sheet music, which is not necessary.  Even though sheet music varies depending on the instrument being played the symbols all have consistent meaning.  A typical piece of music contains all types of measurements, symbols and directions.  A whole note is always a whole note and a quarter note is always a quarter note. Without all of this structure and rules it would be difficult for a musician to perform a piece of music.  It would be impossible for an orchestra to come together and play as a symphony.   When documentation is written inconsistently it is hard to communicate what is desired because inconsistently written documentation inhibits communication and causes confusion. The same is true for software.   When individuals write documentation inconsistently, it is difficult for everyone to understand what was meant. Naturally this hurts productivity and quality.

While it is common for a person writing documentation for a software project to decide on how to write the documents, a composer of music does not decide to develop his own vocabulary or develop their own symbols.  The idea of music composition is an advanced mature industry.  Individuals that write music are trained to write music and they are trained to read music. There are special courses required for those musicians who write and transcribe music.  It is possible for a person to get a Masters Degree in Music Theory (M.M. Theory) or Masters in Music Composition (M.M. Composition) .  It is possible at some universities for an individual to earn a PhD. in Music Composition.  Think about it, music is so advanced in its notation individuals can obtain Master (and sometimes PhD.’s) in the composition of music.   Granted a person can earn a Masters in Software Engineering, but this is analogous to earning a Masters in Music.  A Masters of Software Engineering is a generalist degree.  The required course work to earn a Masters of Software Engineering varies from university to university.   Even the term software engineer is vague.  Typically a software engineer encompasses everything from a programmer, software architect, software designer,  and manager.

In Mozart’s day music was hand copied by an apprentice because there was no such thing as a copy machine. This was one of the problems with printing and reproducing sheet music because sheet music requires special symbols which are not part of everyday language.   Printers who printed sheet music had to have the capability for music engraving.   These printers had special characters not typically used in everyday life.  Today, scorewritter software contains all the necessary symbols for a composer to write music.   If a software organization decides to use symbols to communicate then it is important to be able to type those symbols.

Since there are no standards for coding like sheet music, the code cannot be the documentation.
Published in: on June 12, 2009 at 01:01  Comments (1)  

The URI to TrackBack this entry is:

RSS feed for comments on this post.

One CommentLeave a comment

  1. If Hungarian notation were still pervasive, what a confusing szWorld it would be.

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: