Sergio and the sigil

Maintainable by whom

Posted by Sergio on 2008-06-17

Let's say you are hired to help build or fix an application. You contract is not for hire and you know that after 3, 6 or 12 months you will be gone to repeat the same cycle elsewhere.

I'm sure we have all seen contractors that will do just about anything to complete the task in the allotted time span, sometimes in detriment of the code quality and maintainability. I'm also sure that if you're reading this then you probably care about this enough to avoid replicating this pattern.

But here are some important things that might go unnoticed in the above paragraph.

  • Define The Task
  • Define Quality
  • Define Maintainability

The Task

In my limited experience, I'd say it would be shocking to be hired to just write code regardless of any parameters, as long as the deadline is met. I don't expect to hear from my client "I don't care if what you write is absolute garbage material but it needs to go live in 6 months."

Even if the client is very much driven by the deadline, even if the client doesn't say it out loud, there will always be an implicit expectation that our solution will have a minimum of quality to survive the planned life time.

Our task is never to just write code. They could have hired a high school intern if that's all they wanted.

Quality

I think the quality of a software product is directly related to how well the product adheres to the specifications. Oh, no, specifications. One more thing to consider.

If we're lucky the specifications will be available and include not only the product feature list but also architectural needs, expected maintenance and upgrade pains.

Again, we are not being given carte blanche, even if it sounds like we are. Maybe the client doesn't know how to communicate that to us, but we ought to know that our design needs to accommodate changes and lay on top of a maintainable platform.

Maintainability

The ease with which a software system or component can be modified to correct faults, improve performance, or other attributes, or adapt to a changed environment - IEEE Standard Computer Dictionary

The IEEE definition above is fine but, after a discussion in the last Chicago ALT.NET meeting, there seems to be an important omission here and the main reason for this post.

Maintainable by whom?

The same way our proverbial consultant from the beginning of the post could deliver abominably graded solutions and run away, so can we — with all our shiny, fancy-pants design and tools.

We have the responsibility of designing a solution that is maintainable by the client with their staff of with realistic chances of finding other contractors that can take it on (not necessarily us all the time.)

We have to weight our design decisions and desire to apply the better tools and architecture against the existing scenario. When discussing the possible solutions with the rest of the team that's a good opportunity to assess what kind of team we have to work with (or work for.) If the scenario doesn't look good, there at least two things that can be done:

  1. Discuss the problem with the client and suggest that the staff would benefit from some training or mentoring, so that we can apply a solution that can be maintained more effectively. Training and mentoring may be strong words, sometimes a few informal sessions with the team can go a long way.
  2. If the above is not possible, then the responsible thing to do is choosing a design that the existing team will be comfortable maintaining after our departure. Knowing when to suppress your good intentions is also an important quality of a good consultant, I think.

Reminder: Giveaway deadline this Friday

Posted by Sergio on 2008-06-16

If you have an interesting story and did not submit yet, please submit it ASAP because we will only wait until Friday afternoon.

How often you have a chance to put your hands on such nice prizes? Let me share a little secret, your odds are good, we have received less than 10 submissions so far.

UdtTypeName and .NET data types in SQL

Posted by Sergio on 2008-06-11

We are working on SQL 2008 for a new project with the intent to leverage the new data types, in this case especially the HIERARCHYID data type. One of the stored procedures we created had a parameter of type HIERARCHYID.

The code that calls the stored procedure was something like this.

SqlHierarchyId nodeValue = GetNodeValueFromSomewhere();
var cmd =new SqlCommand("usp_EnableNode");
cmd.CommandType = CommandType.StoredProcedure;
var  nodeParam = myCommand.Parameters.Add("@Node", SqlDbType.SqlHierarchyId);
nodeParam.Value = nodeValue; 
var enableParam = myCommand.Parameters.Add("@Enable",  SqlDbType.SqlBit);
enableParam.Value = true;
cmd.ExecuteNonQuery();

When running this code we were getting the error "UdtTypeName property must be set for UDT parameters." Since the HIERARCHYID data type is a .NET type in SQL 2008 and we had not played with .NET types in SQL 2005 yet, we scratched our heads for a few minutes.

We tried both:

nodeParam.UdtTypeName = typeof(SqlHierarchyId).Name; 

And

nodeParam.UdtTypeName = typeof(SqlHierarchyId).FullName; 

But the solution was much simpler:

nodeParam.UdtTypeName = "HierarchyId";

This should be needed for the new GEOMETRY and GEOGRAPHY data types as well. Maybe this helps someone else.

Excel is the business format, automate it

Posted by Sergio on 2008-06-09

One thing I realized when working in large companies is that Excel is the true data exchange file format. That what the business types exchange among themselves and how they like to persist any kind of lists or anything that needs to be formatted like a table (be it tabular data or not.)

All too often one of this documents is forwarded to me containing some form of business data that will become all sorts of things: lookup data, configuration values, updates to an existing table, etc.

I dread these conversion tasks when I have to do them manually so I tend to automate the task as soon as it smells like a candidate for recurrence. That way I'll take a hit on the first time and reap the benefits from then on.

For some reason I like writing these automation scripts in Ruby. I could probably almost as easily write them in VBScript, C#, PowerShell or even VBA but my experience with Ruby is that it tends to be shorter (as in more concise) and easier to develop. Of course that varies with your level of familiarity with the Ruby libraries, but the learning curve isn't bad at all.

Consider the following hypothetical layout for an Excel file dropped in your inbox for import.

DescriptionPriceCategory
1DVD Player76.49Electronics
2Rain Coat35.10Men's apparel
3Code Complete49.99Books
............
12024" Monitor499.99Computer Accessories

My typical script to process such file would be the obvious line-by-line read, maybe processing each cell before ultimately converting the row to its final format (or skipping that row.) The skeleton of that kind of script is shown below.

require 'win32ole'

begin 
  excel_app = WIN32OLE.new('Excel.Application')
  book = excel_app.Workbooks.Open("c:\\project\\data\\datafile.xls")
  sheet = book.Worksheets(1)
  #first row contains only the headers
  row = 2 #start at the 2nd line (excel is 1-based)

  #stop when we find an empty row
  while sheet.Cells(row, 1).Value
    data = []
    (1..4).each {|c| data[c] = sheet.Cells(row, c).Value }
    #at this point the 'data' array contains the entire row
    #use it as desired *********
    
    row += 1
  end
  
rescue 
  #oops...
  puts "There was an error: #{$!}"
ensure
  #cleanup
  excel_app.DisplayAlerts = 0
  book.Close if book
  excel_app.Quit
end

But, no matter if you use Ruby or any other language, the value in automating these tasks can be tremendous. Taking the time to learn the basics of Excel automation is, in my opinion, very important and will let your users continue to use the tool that they like.

In a kind of reverse example, I have had occasions when one of the business users was repeatedly requesting for some of the data in Excel format during the application development (while we didn't have a web page to show that data yet) so, after he asked for a updated report for the second time, I created a script to read the data from the database, create an Excel file, and send the file attached in an email message every Monday morning. Easy way to gain a happy user.

Update: As noted in the comments, one nice reference for automating with Ruby is Ruby on Windows

The Great Devlicio.us Giveaway

Posted by Sergio on 2008-06-05

Because there's more than one kind of hero

Update: The contest is now closed. We cannot accept any more entries. Wait for the winner announcement is a few days. Thanks for all the great submissions.

Here's your chance to win a well-deserved prize for being a good developer — and not just any prize. Devlicio.us, with the generous support from Microsoft (via Somasegar) and Addison-Wesley, is proud to present you with a contest that will dump a truckload of goodness at your doorstep. This ultimate prize package contains the following items.

  1. Agile Principles, Patterns, and Practices in C#: Uncle Bob's must-have work. This book needs to be part of your Agile and OOD bookshelf.
  2. Domain-Driven Design: Tackling Complexity in the Heart of Software: Eric Evans describes DDD and how your software design can benefit from it.
  3. Applying Domain-Driven Design and Patterns: Armed with the DDD knowlegde, now it's time to let Jimmy Nilsson show us how to implement solid .NET code.
  4. Patterns of Enterprise Application Architecture: In this classic, Martin Fowler lays down the law on how an enterprise application needs to be designed.
  5. Working Effectively with Legacy Code: We've all been there. It's hard and Michael Feathers does a great job in guiding us through the challenges and techniques to get you out of the quicksand.
  6. Implementing Lean Software Development: This book by Tom and Mary Poppendieck distills practices to optimize the development process.
  7. The Pragmatic Programmer: From Journeyman to Master: No list of this caliber would be complete without Andy Hunt and Dave Thomas' ultimate guide to developer proficiency.
  8. Visual Studio 2008 Team Suite + MSDN Premium: No need for explanations here. A $10K+ retail value item with all you'll ever need in terms of Microsoft technology.



The Contest

I hope the prizes got you excited. I actually envy you because I cannot participate. The contest is pretty simple.

  1. We are looking for success stories. Submit a true story that happened to you or your team where adopting good software development practices rescued a project or even the entire organization. The stories we want to award are the ones that demonstrate a direct relation between good practices or good design (or both) and successful solutions. Examples:
    • Continuous Integration saved my job.
    • DDD made my application survive the test of time.
    • My team went from grumpy to engaged after we introduced collective design ownership.
    • etc...
  2. Submit your stories by email or using the Contact link to any of the Devlicio.us bloggers between today (June 5th 2008) and ~2 weeks from today (June 20th 2008 by 5 PM ET GMT-4:00).
  3. The winner will be chosen by voting among the Devlicio.us bloggers. This might take up to 1 week.
  4. The winner story will be announced on Devlicio.us on or before June 20th and it will become a guest blog post on the blog to which it was submitted (so remember to protect the innocent in your story.)
  5. Shortly after that, the winner will be contacted for mailing address information and the prize will be shipped.
  6. Other stories might be selected to feature as blog posts as well - with or without any prizes.

Restrictions

The stories need to be of your own personal experience, within your team or your organization. Since the story has a chance of being posted in Devlicio.us, make sure the people and organizations mentioned in the story are OK with that or replace their names.

We think we can ship the prize anywhere but if you're not in the U.S. and there's some form of export or import regulation that prohibits the shipment of software or even the books, then we may not be able to send it to you.

Get to the writing already

We are anxious to hear your stories. Prizes like these don't come by often and we really want to reward someone for doing the right thing.