Search code examples
.netdocumentationcode-readability

What is the best way to document data reader method calls?


When working with namespaces such as System.Data.Odbc or System.Data.OracleClient the various data reader methods generally require an integer corresponding to a column be provided to the functions (e.g. OracleDataReader.GetInt32).

My question is this, what is the best way to work with these functions so that the code is fairly self-documenting. Right now, it seems to me that there are three options, namely:

// Option One - Just provide the integer value
string myString = oraData.GetString[0];

// Option Two - Provide the integer value using a constant
string myString = oraData.GetString[FIELD_NAME];

// Option Three - Provide the column name and use System.Convert to return the correct value
string myString = Convert.ToString(oraData["Field_Name"]);

Each of these techniques seem to have there own pros and cons and I'm curious to see what others think, or if there is a better way to do it.


Solution

  • I agree with Andrew Hare, with the addition that I've enclosed the functionality in an overloaded extension method that simplifies the operation:

    public static string GetStringByName(this OracleDataReader reader, 
                                         string columnName, 
                                         string defaultValue)
    {
       string result = defaultValue;
       int columnIndex = reader.GetOrdinal(columnName);
       if(!reader.IsDbNull(columnName)
       {
          result = (string) reader.GetString(columnIndex);
       }
       return result;
    }
    

    Anyway, just a refactoring that helped me tremendously.