Dugald Wilson's Blog

Commenting Anti-Patterns

2008-08-13T23:47:14-04:00:00

I've had the opportunity to do some code archaeology lately, and have found a few lessons that bear repeating when it comes to comments. There are a few patterns in use which need to be addressed:

Big Wall of Text

This long, rambling preamble can be found in many legacy applications. Though it does have some use in often providing a name to the faceless coder that is causing you such grief, other than that it has little reason to exist:

/************************************************************************
NAME: test
PURPOSE: 
REVISIONS:
Ver Date Author Description
--------- ---------- --------------- ------------------------------------
1.0 7/8/2008 1. Created this package.
*************************************************************************/

This is a Comment

Really just a statement of the completely obvious in code. If these comments help the next developer of your code, you probably don't want them touching it anyway:

if (!Page.IsPostBack)
{
  // first time
  InitialSetUp();
}

Change Management:

Often put in as a CYA for developers who think the next person to view this code may question their decisions, so change documentation appears directly in the code:

//************************************************************************
//Input parameter changed to false for CommonFilter1.CheckBoxChecked,
//please see request-666899.
//************************************************************************
CommonFilter1.CheckBoxChecked(false);

Timestamp of Changes:

I really don't care when you did this, and if I did, source control could tell me:

//*********************************************************************************
// Changes made by OtherDeveloper on May-15,2002 at 6 pm.
//***********************************************************************************

Please feel free to share other examples of Commenting Anti-Patterns you have encountered!

Learning to Love Ruby

2008-08-12T21:15:25-04:00:00

I've started really stepping up my interest / learning in Ruby, and had one of those "this is great!" moments I wanted to share.

At work, we've been pulling some names, etc out of the DB that aren't kept in the correct case, but need to be presented in an eye-pleasing manner to the user. How do we do this?

Since we're talking about strings, a first check of the string class yields ToUpper(), ToLower(), but no CapitalizetheFirstCharacterAndLowercaseTheRestPlzKThx(), so we will have to keep looking.

Capitalization of names is affected by the culture, so this may be found in System.Globalization. Sure enough, TextInfo::ToTitleCase() is what we are looking for.

So, there is a little extra work to get the conversion to correct capitalization. I need an instance of TextInfo to pass my text to. Not too bad, but here we go:

string passCapitalization = "testing";
System.Globalization.TextInfo  textInfo = System.Globalization.CultureInfo.CurrentCulture.TextInfo;
Console.WriteLine("{0} converted to title case: {1}", passCapitalization, textInfo.ToTitleCase(passCapitalization));

And the output:

So, how hard is this to do in Ruby?

Yes, it's easy, but what about for a real business application, where you'd want to capitalize all the words in a sentence?

Ruby's capitalize string method won't do it, but TextInfo::ToTitleCase will.

string doubleCapitalization = "double testing";
Console.WriteLine("{0} converted to title case: {1}", doubleCapitalization, textInfo.ToTitleCase(doubleCapitalization));

Luckily, Ruby is just our language, and Rails is actually our framework. Rails extends the string class with a titlecase method that does just what we need.

The feeling I got when discovering this was that in using the language and framework, doing what I wanted to do was easy and straightforward. It just worked.

As a semi-unrelated aside, I feel ToTitleCase is broken in the .Net Framework. If the output is supposed to be in title case, why does the format of the input matter? Why does it do nothing when the input is all caps?

string failCapitalization = "FAILING";
Console.WriteLine("{0} converted to title case: {1}", failCapitalization, textInfo.ToTitleCase(failCapitalization));

TriNUG August 2008 - Jeffrey Palermo - TDD, DI, and SoC with ASP.NET MVC

2008-08-06T09:33:50-04:00:00

On Wednesday, Aug 13, Jeffrey Palermo will be talking about separation of concerns, dependency injection, and test driven development with ASP.Net MVC. This should be an excellent discussion on some of the benefits in using the new MVC framework for ASP.Net.

There are some important points to underline about this meeting:

It will be awesome.
Registration is required to manage headcount, especially for our dinner arrangements. To attend, you must register on the site.
This meeting is not at RTI. The August 13 meeting will be held at ECPI.

This should be a great meeting. Hope to see you there!

BarCampRDU 2008

2008-07-31T14:21:56-04:00:00

BarCampRDU is almost here, and I cannot wait! I attended my first BarCampRDU a year ago. I volunteered, and got to meet many great folks, and the sessions I sat in on were just great - full of smart people eager to share their ideas and experiences.

The last BarCamp I attended I knew no one. I think that was really a great way to come in. I could focus on the sessions, and what really appealed to me, versus finding my friends and trying to stick with them. It will be interesting to see if knowing a dozen or more folks at this one changes things.

At the last BarCamp, I did my part by volunteering. I didn't feel like I had an area of expertise to speak in, so I didn't offer up a session. After attending, I now know you don't need to be an expert to lead a topic - often the best topics are discussions that bring together lots of folks contributing their ideas. So in that spirit, I have a few ideas that might make for good discussions:

What's the deal with airline food Twitter?

I want to start a business that isn't headed for an IPO or acquisition. Is there a place for me in RTP?