Needs Improvement

Colin Coller's Blog
Posts: 62 | Comments: 156 | TrackBacks: ?

December 31, 2004

"importnat vales"

I was reading through some of the code that attaches one of our new .NET products to our old ColdFusion products when I found these comments:

<!--- update the proejct with importnat vales that CFSTOREDPROC tag can't handle --->

<!--- if this fails log and contuinue with process --->

<!--- create database objects and some defautl data entries --->

<!--- delete temporay datasource ---->

I expected bad code, and in that sense the code doesn't disappoint, but I'm blown away by the comments. "proejct"? "importnat vales"? I know the programmer in question can speak and write English fluently, and I know he can spell all of these words correctly, so why are there so many spelling mistakes in his comments?

I had the following comment on my peer review: "Your expectations for others are too high." Is expecting correct spelling and grammar in comments really too much? Isn't the care and attention paid to writing the comments at least partly indicative of the care and attention paid when writing the code?

What do all of you think?

Colin

10:43 AM | Colin

TrackBacks

# Tsunami Victims

03:00 PM | Test Driven .NET

# free ringtone ?????????¦???????

12:43 AM | free ringtone

# discount airfares ?????????¦???????

05:19 AM | discount airfares

# airfares ?????????¦???????

05:23 AM | airfares

Comments

# RE: "importnat vales"

I think that the problem probably lies in a lack of understanding or agreement with the need for clear and useful documentation. Often when programmers are instructed to make changes to their workflow which are viewed as improvements by the management, they can see this as invasive, perhaps even nosy. Especially if they have been working the same way for a long time, and in their mindset it is the true path to follow. I can imagine people might be reluctant to the change and perhaps rush the documentation process, because they don't wholeheartedly agree with it.
The examples you give here Colin are probably caused by fast typing, which isn't corrected or read after it is being typed. But I am stating the obvious here ofcourse. You will see that syntax isn't spelled wrong, because of two reasons:
First of all it wouldn't compile :)
Second of all, it is prevented by using autocompletion.
Several IDE's offer spellchecking in sourcecode comments, and I have even seen some that autocomplete and autocorrect (like Word) english words in comments.

Regarding the care and attention point, I am not sure. They are being rushed because the programmer rather does what he likes more: write code. Therefor I think the care that goes into writing documentation is not indicative of the care and devotion when it comes to writing code. The main point is to be able to convince the programmer of the need for effective and useful documentation, without putting it on him/her as a rule from above, because that will work against you perhaps.

12:57 PM | Yves Janse

# RE: "importnat vales"

Yves:

We don't really have rules for commenting our ColdFusion code. If a programmer thinks it's important to comment something, he comments it. If not, he doesn't. The comments are there because the programmer thought it was important that they be there. Perhaps he added them to help him keep track of what he was doing, not to help others understand what he did, and so spelling didn't matter.

You're right, it's not spelling, it's typing. But:

If he was typing so quickly that he made mistakes in the comments, where else might he have made mistakes (interpreted ColdFusion 4.5 code, SQL, HTML, text, etc)?

If he was rushing through the boring stuff to get to the interesting stuff, what else did he find boring and rush through (analysis, design, testing, boring parts of implementation like error handling and recovery, etc)?

I'm not this programmer's manager and I'm not about to make or enforce rules for ColdFusion code (I rarely touch the old products). I'm just wondering if my expectations are too high and if my misgivings are misplaced. :)

Cheers,

Colin

02:18 PM | Colin

# RE: "importnat vales"

I used to work with a guy who was constantly breaking our code. He would put fields into the database...and tell you "it's in the receipts field" or "it's in the patients table" and so on.

So...fingers flying, we select from patients where FirstName = blahblah and get errors.

Because...we should in fact have been selecting from "pateints" where "FurstName" = blahblah. We bought him a word-a-day calendar and subscribed him to some dictionary email list.

You aren't expecting too much. Programmers are supposed to be intelligent. If you can command a computer language, you should be able to command English at least at the 10th grade level.

11:44 PM | Scott C. Reynolds

# RE: "importnat vales"

Colin your expectations are not too high. Programmers should at least re-read the comment they just typed (fast or otherwise). Bad spelling is indicative of disregard for attention to detail which is a characteristic of professionalism. I had a colleague who’s spelling mistakes spilled into variable names. Worst, we had a VB COM component which exposed a class (default interface) NetworkFarme and couldn’t change it due to binary compatibility issues; he found it funny... I didn't (every time I tried to new up a Frame)!

07:25 AM | Daniel Moth