Bitten by Performance Counter issues in Virtual Machine

I've been using virtual machines for software development for just over 3 years now. At this point, virtually all of my software development is done on virtual machines (no pun intended... it was just a side effect).

About 8 months ago, I started noticing a recurring issue on my virtual machines with regards to SQL Server 2005. I was regularly getting errors in the application event log about SQL Server 2005 performance counters. Since this was the only error I was getting, and SQL Server 2005 seemed to plug right along just fine despite these errors, I ignored them.

Fast forward 8 months to today. I've been using SQL Server 2008 in development projects for a few months now. I had one particular virtual machine that did not have SQL Server 2008 reporting services installed and I wanted to install it today. When I ran the installation wizard, it kept failing during initial check steps, reporting that there was a problem with the performance counters. In this case, it would not let me install reporting services withough resolving this issue. The details reccomended following the steps of Microsoft KB article 300956, "How to manually rebuild Performance Counter Library values".

I followed all of the steps of this KB article (not a quick task mind you), rebooted and started the installation again. Much to my chagrin, it failed due to the same performance counter check failing AGAIN..... UGH!

Some additional googling let me to this blog post.

The short story here is that performance counters were disabled.... ALL OF THEM. Rebuilding them was a completely unnecessary step. I also know why they were disabled, and I will remember this for a LONG time to come.

I've been using VMOptimizer from Vizioncore (desktop version now discontinued) since before it was purchased by Vizioncore from Invirtus (or they merged, or whatever happend). There is a checkbox in the opimization options regarding disabling disk performance counters. Unfortunately, this is mislabled. It doesn't disable "disk performance counters", it simply turns off ALL OF THEM.

Guess when I started using VMOptimizer again.... say... about 8 months ago.

If you need any performance counters turned on, don't check this option or possibly suffer the same fate that I did.

JE

Employ "white space" in your code

Make your code more readable (by not jamming it all together) and, therefore, easier to maintain.

Examples:

  a) Code examples:

    Without white space, the code is not as readable:
      REPLACE CB_UnitsBilled WITH ;
        (lnBillableDaysTotal/DAY(GOMONTH(C_ClaimHeader.CH_From,1) ;
         -1))*CB_UnitsBilled

    With white space, the code is more readable:
      REPLACE CB_UnitsBilled;
        WITH ;
          (lnBillableDaysTotal / DAY(GOMONTH(C_ClaimHeader.CH_From, 1) ;
           - 1)) * CB_UnitsBilled

    Of course, with good comments, the command makes the most sense:
      * Units Billed = (Total Billable Days / Total # Days in month) x
      *                Authorized Units
      REPLACE CB_UnitsBilled WITH (m.lnBillableDaysTotal /    ;
         DAY(GOMONTH(C_ClaimHeader.CH_From, 1) - 1)) * CB_UnitsBilled

  b) Inserting a space after each semicolon (";") makes your PATH setting in configuration files and SET PATH commands in VFP code more readable:

    Without white space, the path is not as readable:
PATH = C:\App;C:\App\Data;C:\Program Files\Microsoft Visual FoxPro 9;C:\Stonefield\SfCommon;C:\Stonefield\SDT;C:\Stonefield\SDT\Source;C:\Stonefield\SDT\DBCX

    With white space, the path is more readable:
PATH = C:\App; C:\App\Data; C:\Program Files\Microsoft Visual FoxPro 9; C:\Stonefield\SfCommon; C:\Stonefield\SDT; C:\Stonefield\SDT\Source; C:\Stonefield\SDT\DBCX

The above examples demonstrate intraline (horizontal) white space (making it easier to read your code from left to right); also employ interline (vertical) white space (to make your code easier to read from the top down).

Is it October yet?

Although, here in Kansas City, it still feels like October (kinda chilly), we are many months away. Still, I am anxiously awaiting for October 2008 to arrive because that is when the Southwest Fox 2008 Conference will take place. Last year's Southwest Fox 2007 Conference (featuring EVERYTHING you ever wanted to know about Microsoft Visual FoxPro) was the most attended ever; bucking the trend of reduced attendence at VFP conferences. There is no reason why this year's conference can't be even better. It was HIGHLY received by the attendees last year, and first time organizers, Tamar Granor, Rick Schummer, and Doug Hennig are in the process of building upon last year's success.

There are several ways in which the conference can be improved and one of them is to spread the word throughout the FoxPro community about the conference. It is in that spirit that I am pointing you to one of the pages on the ( Southwest Fox website ) that is specifically designed to assist community members in publicizing the conference, the ( "Promote the Conference" ) page. On that page, you will find several ways to help promote the conference and spread the VFP "Word".

I am particularly directing your eyeballs to the section displaying two animated banner ads. One (or both) of these banner ads will easily fit onto a page of anyone's website and/or blog. You can cut and paste the HTML code provided to easily display the banners. It would be a genuinely unselfish gesture if each and everyone of you reading this blog would take the time to post an ad (as well as pass along the URL to the promotion page to others likely to post an ad). Incidentally, if you don't, it will reflect on your parents and a big, black checkmark will go on your permanent record. Seriously, anyone who loves Fox and wants to see it continue to flourish is encouraged to post an ad banner. Your help in making the 2008 conference the best one yet will be greatly appreciated.

Lastly, if you are interested, the call has gone out to all those interested in being a speaker at the 2008 conference.  Details are on the Southwest Fox website.

Sometimes, It Is the Small Things In Life That Count

Has this ever happened to you?  It happens to me a minimum of once a week, but NOT ANY MORE!  Most often it happens when I am copying a directory (yes, I am “old school” and refuse to say “folder”) full of files from a hard drive to a thumb drive. I know that the process will take a few minutes so I begin the copying and go get a drink refill.  Adding fresh ice, topping off the glass, and meandering back to the computer, I notice a message on the screen.  Have you seen one similar to this before?!?!

                    

While not completely wasted, the time getting my refill wasn’t as productive as I thought it would be because the copying process did not complete, but, instead, paused waiting for my input. I said “Yes”, but then had to wait for the process to complete. What a pain. Oooh, thank you Microsoft. I certainly wouldn’t want to overwrite a file that I can recreate any time I want to (usually whether or not I actually want to). The fact that it is referred to as a “system file” makes it seem that much more important, too. Well, in MY opinion, (I use the phrase, “in MY opinion” so that if I am wrong in anything I say, I can just say that “MY opinion” was based on MY experience) there is very little upside by even having these Thumbs.db files hanging around all over the place.  If there was only a way to prevent them from propagating like tribbles in heat.  Hey, there is!

I ASSume that the main purpose for these files is to have a way to easily (and quickly) see thumbnail images of any graphics files.  Nice concept, no problem. It does take some amount of overhead to create the file, but to me, the time is insignificant unless you had a couple thousand .jpgs in a directory (and then, I would question THAT behavior). At any rate, you can prevent the OS from automatically creating (AND THUS, ELIMINATING THIS ANNOYING “FEATURE”) as follows:

Open up Windows Explorer, go to the menu Tools|Folder Options| click on the “View” tab, and under the “Files and Folders” section, look for the checkbox with the caption, “Do Not Cache Thumbnails”. Stick a big, old, fat check in that box and from now on the Thumbs.db file will not be written to your hard drive. Yes, you WILL still be able to select Thumbnails as a format to view the directory’s files, but since it is not written to disk, it is never copied, and you will never see the above message again. As I mentioned, there is a very minor, minor, minor performance hit each time you request a thumbnail view, but it is a small price to pay (again) in MY opinion. Ah, life is good.  Sometimes it’s the small things in life that count.

When to Consider Custom Software over COTS?

When your business requires a software solution, you have two directions in which you can go — Custom or COTS (Commercial Off-The-Shelf). Which path you choose depends upon considering a number of factors. It is our goal to arm you with information that will enable you to make the best business decision.

For this article, we will define “custom” software as computer software that the business owner has contracted to have written for their company. Traditionally, custom software is written by a third party entity; usually an outside software development company or a team of in-house personnel. COTS software is usually purchased from a retailer or from a vendor who has developed the software and mass-markets their product to many businesses (usually within a vertical market).

It’s not always easy to decide between custom or COTS software since it often requires long hours of deliberation and an understanding of the pros and cons of each choice. In the spirit of full disclosure, the authors’ main source of income is derived from creating custom business software; however, since we realize that there are times when custom software is not the best solution, we will attempt to present a balanced description of the pros and cons. Reviewing the following pros and cons will make that daunting task easier.

Custom Software – PROs:
Gives you exactly what you need – Each business has its own set of unique business rules. Often, the only way they can be computerized is via custom software. Why pay for features that will never be used?

You own the source code – Owning the source code affords you more control over future enhancements. When clients see the value of custom software, they become more sophisticated and quickly find specific ways to improve their particular business work flow. When ideas pop into your entrepreneurial brain, you can have the existing software modified to incorporate those ideas. Additionally, owning the custom source code is a valuable asset; an asset that should be included in the price of the business if it is ever sold.

More useful reports – There is no reason to have software unless it can produce the desired output; this is often in the form of reports. Custom software allows for the creation of meaningful reports that are used to make astute business decisions. You, the business owner, can ensure that reports give you the information the way you want it; not how the vendor thinks you want it.

More efficient in-house help desk – Help desk personnel will be more familiar with the business rules involved and can assist users. They will know about common issues, traps, and work-arounds. This is much better than having to explain a specific issue to COTS help desk personnel who usually deal with generic problems.

Decision makers are readily available – During the design phase, decision makers are available to make judgment calls. They have an intimate knowledge regarding how the software should work. Users are very good at describing the work flow and as a result, the software can be more effectively designed to increase their efficiency.

Vested users readily accept the software – If the users have had input into the design of the new software, they more readily accept the changes. Plus, they are ahead of the learning curve because they’ve been exposed to the software during the development stage.

Money is not wasted on unnecessary features – A side benefit of getting the exact functionality you want in the software is wisely spending your development dollars. Every dollar that is spent goes toward making the best possible product.

No major license fees – You own the code. You own the software. You control its use. This is not to say that annual fees, hardware enhancements, and other “cost of doing business” expenses don’t exist. Most likely, they will exist, but you will need to find out what they cover, how much they are, and compare them to the same fees for the COTS software.

Custom Software – CONs:
May cost more – It is custom software and one would expect to pay more because custom “anything” is labor-intensive. Depending on the scope of the software’s capabilities, it could be considerably more expensive than “canned” software; only you can decide if the derived benefits are worth the expenditure.

Not immediately available - Depending on the number of developers, the scope of the project and other factors, it may take months for the application to be created. This may be greatly reduced by using developers who employ proven software development practices such as a framework, agile processes, test-driven development, etc.

You may be re-inventing the wheel – Most applications have many of the same features as requirements; printing reports, displaying data, and adding or modifying data are such examples. Time, money, and effort will have to be spent with respect to these basic tasks.
 
COTS Software – PROs:
Immediately available – Upon purchase, the software is yours. Deploying the software and establishing the user environment is up to you; as is getting it to do exactly what you want.

May cost less – The initial cost will almost certainly be less than any custom software. You may have a licensing obligation, though, where you must pay a fee on a per-user basis.

Don’t have to re-invent the wheel – For performing basic data functions, COTS software should be able to do the job. Basic customer, sales, basic reporting, and invoicing tasks could be handled as long as you are willing to do it the way the vendor wants you to do it.

Technical support – Technical support is sometimes free; sometimes, it’s pay-by-incident. Hopefully, the COTS personnel know their package and can relate to your specific issues.

COTS Software – CONs:
Little extensibility – The software may or may not be able to implement the features you desire. However, some COTS packages allow for some extensibility via a user scripting tool or via a report writer that enables the user to develop their own custom reports.

Usually “work-arounds” are required – There may also be additional expenses to implement required “work-arounds” to handle specific needs for your particular business; even then, you might not get the result you desire.

At the mercy of the manufacturer – You have no control as to when updates, bug fixes and new features will be available or even if they will ever be available. Vendors typically respond to the concerns of “squeaky wheels”. If you are the only one experiencing a specific issue, it could be a long time before it is addressed, if ever.

Non-Vested users can become frustrated – Users have no vested interest in “canned” software and there is a psychological component when installing new software. Users are placed on the “learning curve” and it usually isn’t fun for them; people are reluctant to change.

Potentially major license fees – Some vendors charge annual license and/or subscription renewal fees.

In summary, if you find a COTS package that meets your requirements and is reasonably priced, then go with it. However, if you need a solution that more closely meets your business requirements, implements rules for your specific business (not just for the vertical market in which your business resides), and is flexible enough to change as your business changes, then you would be doing your business a disservice by not considering a custom software solution.

- Art Bergquist and Dave Aring

Jim, I hate you.

I was working on site for a client recently when I said, “Jim, I hate you.”

Jim’s head pops over the side of the cubicle next to me. He flashes me a quizzical look and asks, “Why is it that?

“Because, I can’t write a single line of code now without writing a test to support it. It is all your fault.”

He smiles and replies, “Well, if you are blaming me for writing better code, I’m ok with that.”

Just in case you don’t know, Jim Erwin is our resident rock star (literally, he was a musician in a previous life) and the author of FoxUnit, a unit testing framework for Visual FoxPro. He is also the Software Development Practice Manager and the evangelist for Test Driven Development (TDD) at Visionpace. In addition to having a great sense of humor he is my ever patient coach on TDD.

I took my first TDD course from Jim and I have been incorporating it into my development practices ever since, but not without some trepidation. I try to keep myself open to new methods and try not to discard a new idea until I have tried it. I will usually adapt a new idea into my development and practice it for a while before I make up my mind on how useful it is. My first impression of TDD was that it really wasn’t that different from how we always did things. Other than that whole idea of writing a test that was bound to fail before you even start, how different could it be? We always test our code, right? I mean, it is not like we write some code and just throw it out there for our users. So how is that TDD thing so different?

It wasn’t until I developed the habit of testing my software with unit tests that I really found that out. I have to admit that it wasn’t easy at first. There were all kinds of problems. Most of which I created by not following good practices. Early on I wanted to test everything with FoxUnit. I tested forms and reports and anything that was part of my application. But that is not what unit testing is all about.

As I progressed as a student of TDD, I began to realize that unit testing meant just that. You test units, not complete applications. As developers we are familiar with the concept of writing small pieces of code with discrete functionality. I realize that I’ve known that for years. It was something that I was taught in college, and that was longer ago than I want to admit. However, it wasn’t until I started unit testing that I really became aware of what that meant. I thought I knew and practiced that.

The more I tried to test my software the more I started thinking of how I could break it down into testable units. There were times I wanted to test some object but I would end up testing ten other things at the same time because of the built-in dependencies.  That forced me to look at how I could reduce those dependencies.

As I continued to practice TDD I found myself thinking of how I was going to test the software before I wrote it. When I realized that, I also realized that I wasn’t really doing TDD. When you practice TDD, you write the test first and the code later. What I had been doing was writing the code first and trying to find a way to test it later. When I started writing the test first, I started finding ways to reduce the dependencies. 

Jim, I hate you because I can never write code the same again. You taught me to use TDD. You opened my eyes to a different way to write software. You forced me to see some of the imperfections in how I write code. My code is cleaner because of you, and I have the tests to prove it.

Jim is smiling, and he is ok with that.

…

If you are using FoxUnit or practicing TDD, I would love to hear about your experience. Send us an email or stop by FoxUnit.Org and let us know what your experience has been.

All Those Who Liked Doing Book Reports in School, Raise Your Hand

I hated doing book reports in school. I usually tried to “read” a book that had been made into a movie. I preferred to “watch” a book rather than read one. I gave up this approach when I once reported on Jules Verne’s “Around the World in Eighty Days”. Turns out the much bally-hooed scene of Phineas Fogg going over the Alps in a hot air balloon was never a part of the actual novel; it was just a Hollywood gimmick and my English teacher was aware of that fact. Anyway, why would I want to read a book when I could be outside playing? I haven’t changed too much over the years. Why would I want to read a book when I could be inside playing (on the computer)? I rarely read for pleasure, but I almost always have a technical book, white paper, or trade magazine with me. You just have to “grow ‘til ya go”.

The latest book I have been schlepping around is “Flying Fox – Applying Visual FoxPro Reporting to Any Data, in Any Environment” by Lisa Slater Nicholls. “Flying Fox” is an easily portable paperback (about 140 pages) offered by dFPUG (Deutschland FoxPro User Group). In Europe, it may be ordered at http://tinyurl.com/2pa32x. Here in the colonies, Whil Hentzen’s Hentzenwerke Publishing is handling the domestic distribution and can be ordered at http://tinyurl.com/2naej6.

What this book lacks in physical presence, (it is just an average sized paperback), it more than makes up for with content and the urge to think “outside the box” with respect to creating application reports. The introduction sums it up quite nicely. “Database developers who have never used Visual FoxPro can use this book to learn how to use VFP as a low-cost and full-featured reporting tool for their data sources. Even if you don’t use VFP for anything else, VFP makes reporting accessible, extensible and cost-effective.” What business owner would not be impressed by that degree of flexibility and cost? Not many. I want to re-emphasize that this book and its concepts are not for Visual FoxPro users only. One word of caution… If you are using a version of FoxPro that is earlier than VFP 9.0, you will have to upgrade to take advantage of all of the concepts; specifically, the use of the report listener classes. Another important point is that even though Nicholls states that you don’t need to know VFP, you will have to learn some FoxPro. However, this should not be a showstopper since she takes several chapters to draw you into the VFP environment as well as explain the commands needed to accomplish your goals.

Additionally, more chapters are devoted in the step by step development of a VFP reporting application. In summation your honor… I would like to state that I have read through the book twice and although I consider myself to be somewhat savvy report-wise, I still do not fully understand all of the concepts. It is not because of Nicholls’ explanation, but rather, reluctance on my part, to get my hands dirty since I do not have an immediate need for this functionality. I am confident that once I actually place my fingers on the keyboard and start to build my reporting application it should all come together. For me, it is simply a case of adding another tool to my development arsenal and I am suggesting that you consider making yourself aware of these reporting possibilities also. Read the book, now! It will be years before Hollywood makes it into a movie.

Porters! Presort!

Most of the applications I write are data-centric. People put data IN, the application manipulates the data in some way, and people take data out. Nine times out of ten, the data is taken out by putting it into some readable format.  I like to call that readable format a report; oh, wait, so do 100,000 other developers. Nothing new there, but the 100k number is greatly reduced when those developers are asked if they actually like to CREATE a report.

For the most part, creating reports is not glamorous. Creating reports (much of the time) is not very challenging. Let’s face it, creating reports is quite boring. However, just as I would like you to look at the title of this blog in a different way, looking at reports from a different perspective may allow you to gain respect for this much, maligned aspect of application development. So, looking at the title from a different perspective… you might see… Reports!  Reports!

Many senior developers just pass off the task of creating the reports to the junior developers.  If that is your M.O., so be it. At the very least, I am suggesting that you take on the additional responsibility to review all of the reports that are produced from within your various applications. Here are a few reasons why.

1. Quite often the person who ends up reading the report is the same person that approves the check that is given to you for your services. i.e Middle to upper management. The “grunts” enter the data, the application processes it, and the data flows uphill to management. It is often the case that management bases the success of the application development process on the physical output – namely the reports they read.

2. If those reports are clear and concise this is a good thing. If they are easy to read and understand, this is even better. Even nicer is the fact that columns line up, fonts match, data is accurate. In other words, it gives the management-type a “warm and fuzzy” feeling in their tum-tums.  That is definitely a good thing.

3. A group of reports that are “standardized” is a factor in making the overall application appear to be professional. Using similar formats for cover sheets, using similar (if not identical) fonts, and standard headers and footers go a long way in allowing the reader to interpret the report. Much like following a standardized menu design that is similar to other menus in Windows-based applications, a standardized set of reporting design features enhances the overall application.

Give the design and format of your reports the same care you give your code and it will pay dividends. Give reports the respect they deserve. You will be glad you did.

Why use Tasks?

As we coach software development teams in Kansas City, we are often asked about the process of breaking User Stories down into development tasks (anything related to implementing and verify a User Story). This is one of the areas teams struggle with when adopting an Agile process. It's actually something they often struggle with using most any process but most Agile approaches rely heavily on it for a number of reasons.

1) Iteration Planning

Tasks are a good last check for iteration planning purposes. Even though we can rely (to some extent) on past  actual velocity to get a sense of what a team might be able to achieve in subsequent iterations, breaking stories down into development tasks/hours allows the team to leverage what they've learned so far during a given release in terms of some stories being potentially larger or smaller than previously thought. They can use that information to develop a better, more reliable/realistic iteration plan.

During planning, openly discussing development tasks gives all team members a view of what will take place while implementing the stories selected for the iteration. During that discussion they can help each other clarify and improve their development plan and discuss lesser known areas of the code, database, etc. to help other team members learn and become more productive in their development.

2) Iteration Burndown (what's left <how many hours> to do within a given iteration)

Having tasks with hours estimates enables the team to discuss (during the Daily Stand Up meeting) why certain tasks might be taking longer than planned, why some tasks were overlooked when a story was initially discussed, why some tasks weren't ultimately needed. With this information, it becomes apparent that at times, developers may be struggling with a given task and may need help.

It also enforces thinking more thoroughly about tasks needed to complete a story and aides in becoming better at tasking and task estimating during subsequent iteration planning meetings. It also allows the team to get an earlier sense of whether the goals and story points planned for a given iteration will be achieved and allows the team to consider adjustments sooner.

3) Accountability

Defining and estimating tasks makes team commitments to an iteration public knowledge and increases
the sense of urgency of getting better at task definition and estimation. It also can help with maintaining a sense of focus on agreed upon tasks and indirectly trims waste related to gold plating. It can encourage team members to seek assistance on tasks they might be struggling with as their 2-hour task still isn't done after a couple of days effort while the teams velocity begins to become negatively impacted.

Developing for a story without tasks can lead to stories that don't get done or done as hoped. Without tasks, the team loses the ability to provide assistance (since nobody knows what you're doing) and overall iteration and ultimately release predictability suffers.

4) Shared and Individual Learning

Discussing, defining, estimating and tracking tasks allows the entire team to learn about the problem domain, especially when the domain or parts of it might be new to certain team members. It also helps all team members become better about planning the work needed for all stories and helps them to become better definers and estimators of tasks.

5) Tasking Encourages Better Design

Thinking through a plan of attack for implementing user stories and creating steps (a.k.a tasks) to achieve it tends to create a higher level of focus and optimize overall productivity. It also facilitates design discussion often resulting in better and more complete story implemenation.

6) Forecasting Velocity

When you don't have the luxury of running an iteration to get an actual velocity but need to provide stakeholders with some sense of cost and schedule, you need to forecast the teams velocity. Using tasks is very effective for this. Do this by estimating team capacity, breaking stories down into tasks/hours until the capacity is filled and adding up the points for the stories you just tasked. You now have a forecasted velocity to provide a preliminary forecast of cost and schedule.

7) Tasks Serve as Reminders

When you task, typically at the beginning of an iteration (during the planning meeting), you have the users  attention and are able to ask questions to which you'll need answers to enable you to think about your plan of attack for a given story in terms of development tasks that will be necessary. Even a few days into the actual iteration, you'll forget at least part of what you discussed with the user if you don't have recorded tasks and you'll have potentially less access to the user to confirm/reconfirm tasks and/or stories.

8) Talk to the Dog

Having to talk out loud and/or in a public setting about tasks you'd need to complete a user story tends to create greater focus than just beginning to code. It typically creates better overall productivity and thoughtfulness in approaching the implementation of a story.

9) What if you hear, "I can't/won't task."?

If a team or team member simply says they won't task, that's more of a personal discussion. Obviously asking them why they won't task would be a useful starting point, it may ultimately speak more to ego, personality or an underlying resistance to change.

When a team or team member claims they can't task you have more information to work with. A common stated reason is that they "just have to start coding" and don't really know about the tasks until they start working on it. One approach is to say "Fine, then write down the tasks as you uncover them during coding and we'll discuss and learn from those to make you a better up-front tasker.". You can also allow a "research" task (2-4 hours) to allow a developer to spend time looking at the code, database, etc. for purposes of ultimately tasking a user story.

Above are just a few broad reasons why tasking is useful for software development, in particular for Agile processes.

Liar, liar, pants on fire!

Before I start this diatribe, give me a minute to get up on my soapbox. Ah, that’s better. The air up here is not as polluted and I can see more clearly now. Too bad some of you can’t get up on the soapbox with me to enjoy the view, but I digress. OK, before going any further, I warn you that I am about to offend a lot of “kool-aid drinkers”.  If you are one of them, tough toenails, because I’ll give you the bottom line right now – you, my friend, are an idiot.  If you don’t have thick skin, read no further. Those of you brave enough to face the truth, continue on.

We here at Visionpace make every attempt to practice the Agile methodology of software development. We are proud of the fact that this practice serves both us, as software developers, and our clients extremely well. Many of our clients were reluctant at first, but once they understood the benefits, most of them gave it a chance and haven’t looked back.

Agile practices are a good thing, but I do have one beef that I am VERY passionate about and I am about to discuss (some of you might even say, proselytize) it. In many agile discussions, as well as discussions about other software disciplines, one often hears the phrase, “All comments are lies.” Those of you who believe this are (as I have alluded to above) idiots! However, those of you who do NOT believe it, COULD still be an idiot, and so, be sure to get a second opinion.

Hey, I get it. Don’t trust comments. They are not always accurate. Duh! I feel that there are a certain percentage of you out there who actually embrace this belief because it validates the fact that you were doing the right thing all those years by NOT putting comments in your code. No, it just validates that you are lazy. Lazy is not, necessarily, a bad trait in a software developer, but NOT commenting your code WITHIN the code makes you, dare I say it, an idiot. That is the last time I will use that term, because, hopefully by now, you are riled up enough to really listen to me.

Other than the fact that someone either knowingly wrote an inaccurate comment or wrote a comment, modified the code pertaining to it, and then did not update the comment, can any one out there give me a reason NOT to trust a comment you discover in code? We will exclude that person from the discussion because he is a “psycho programmer”; you know the one that NEVER follows any kind of standard and use one character mvars. Besides, most “psycho programmers” don’t comment anyway.

Here are the reasons why you SHOULD comment your code.

1. Let’s get the “trust” issue out of the way right now.  If YOU put the comment in yourself, you BETTER believe that the comment is accurate. You did it (primarily) for yourself.  The fact that an accurate comment will benefit a maintenance programmer who comes down the pike a year later is an extra benefit; a benefit which I appreciate when I am called in to do the maintenance. I will be more than happy to ASSume that the newly discovered comment is accurate because THAT developer put it in there and, like you, why would they want to lie to them self? Yes, there is that chance that the comment is now inaccurate.  Studies have shown, statistically, that approximately 93% of comments ARE accurate.  Right here, you should be asking yourself where I got those numbers, and right here, I will tell you that I made them up.  Who would waste their time researching that fact? Nevertheless, think about it, most comments ARE accurate because the person who writes them WANTS them to be accurate.

2. OK, I can tell you are getting a little bit peeved right now. Dave, I thought our code is supposed to be “self-documenting”? If I write bug free code, why do I have to comment? Oh, grasshopper, you will learn someday.  Until then, trust me, write those comments! In all honesty, I, too, am a believer that under most circumstances, the code SHOULD be self documenting. However, consider the following code:
   
   

REPLACE Name WITH UPPER(SUBST (LastName, 1, 2) + LOWER(SUBST (LastName, 3)

That code is self documenting, if someone wanted to take the time to figure out what it does, they could easily do so. The real question the person should be asking their self is... WHY is that code there? It looks kind of goofy anyway.  When I first saw it, I thought that perhaps the coder didn’t know about the PROPER function, but then, they were really capitalizing the first TWO letters of the name. Maybe the parameter of the first substring should have been 1, 1.  Maybe I should refactor using the PROPER function.  I am soooooooo confused!  Close to an hour of my time was spent determining WHY this code was here.  Imagine how much easier it would have been had the following comment been in place.

DLA/Visionpace 04-01-2004 Mr. Jones, the COO, bought 113 file cabinets at an auction. He has decided that the new company wide filing system will be based on the first TWO letters of the customer name. EACH drawer will have a two letter designation and the file will be placed in the drawer base on the first two letters of the customer name. To make it easier to file, he wants the first two letters emphasized for easier reading.

Immediately, we can see that the code is correct and that there is a reason WHY it was written.  Additionally, as often happens to me, in some scrum, when asked why this was done or who requested it, the answer is there.  Not only for me, but for you when you come in to do the maintenance. Two minutes to initially write the comment or 60 minutes to figure out the details three years later. You do the math.

3. Additionally, what one developer feels is self-documenting, another might not. Why not eliminate any potential confusion and explain the reason for the code’s existence? Again, it will save the next person who comes along much valuable time for there is a real good chance that they will know nothing about the project and the code. Believe me, you will benefit also.  One of my favorite phrases is... “When you are coding, you and God know what you are doing.  Six months later, only God knows.” I can not begin to tell you the number of times when I have gone into some legacy code and the comment I wrote three years earlier IMMEDIATELY brings back to life the exact reason for the code.  Many is the time that it has saved my fanny. Those are the times that I almost dislocate my shoulder patting myself on the back for a job well-done.
   
   

If you have made it this far, you are just not getting enough billable hours in.  However, thank you for reading along and agreeing or disagreeing.  Either way, I would appreciate hearing your thoughts on this very polarizing topic. I promise to bring an open mind if you do the same, but I will say right up front, that it will take a Herculean effort to change my mind.  Care to give it a try?