Developer’s English Skills

I don’t have an exact measurement but I would guess that less than half of the time I spend typing I am writing code.  This means that a majority of my typing time is spent writing communications to another human.  This blog is an example of that.  Throughout my normal work day I will compose notes, emails, instant messages, and text messages all of which need to be understood by someone.  Because of this I strive to always compose my writings to the best of my ability.  I am no grammarian, but I can normally successfully convey my thoughts.

Programmers are notoriously bad at writing correctly (at least most of the programmers I know are).  At first glance you might think this isn’t a large issue since we are writing code that only a computer has to understand.  This is untrue.  As I stated earlier, I believe I write for humans more than I write code.  I have had a few experiences where bad grammar in code has had a large negative impact.  I have literally had a bug in my code where I had spelled something incorrectly.

Because communicating with humans is such an integral part of a software developer’s job I hold the developers I work with to a high standard.  I require that the code is well commented and readable.  As well as being commented the comments also have to be full English, grammatically correct sentences.  I even require that member names (properties, class names, variables, etc.) be spelled out with no abbreviations and are understandable when read.  I get a lot of push back from my team about spelling out known acronyms/abbreviations.  I often hear complaints like:

Why do we have to spell out EE?  We all know what it means!

This is a valid point.  EE definitely means Enterprise Edition.  Wait… it doesn’t mean that?  I guess my friend has a different perspective since they are a Java developer.  The correct answer is Electrical Engineer.  What?  I’m wrong again…  That doesn’t make any sense.  Everyone knows what EE means!  There aren’t that many definitions for it.  Oh, I understand.  My current project has a specific definition for EE.  The definition isn’t even listed in the acronym list.  EE in my case is domain specific.  How would a new team member know what EE stood for?  I can’t imagine trying to explain all the acronyms and abbreviations we use to a new team member.  At one point my employer had and acronym/abbreviation list that was pages long.  This also had the same problem of entries being defined multiple different ways.

Being clear on what you mean is the main force behind me enforcing these rules and constraints.  Every once in a while things can go wrong.

NHibernate Search Result

NHibernate Search Result

In this case the title of the posting is technically correct.  When searching for my problem I completely understood the point this person was conveying.  The only downside to this post is the title also has a slightly inappropriate meaning.  It sounds like a headline you would hear on the nightly news.  This title like the EE example is domain specific but slightly amusing with the possible misinterpretation.

Communication skills are important even for developers.  Having comments that can not be understood is just as bad as not having them.  They are just as important as the code itself and should be treated that way.  They have to meet all standards, get reviewed, and be well written.  The effort put forth now to treat comments as part of the code pays off greatly in the long run.  You and others will appreciate the well written comments as you reuse and maintain the code base.

This entry was posted in Technology and tagged , . Bookmark the permalink. Both comments and trackbacks are currently closed.