Recommended Parameter Order

Question

I'm working on a legacy software system, and I've been tasked with migrating some old COM components to .NET 3.5. The COM components were originally hosted in MTS, then in Component Services. In the .NET port, we're handling transactions with ADO.NET transactions, so the method signatures are changing somewhat.

The dilemma I'm facing is the parameter order. Each method requires that you pass it either a SqlConnection or a SqlTransaction (depending on whether or not the method updates the database). Some methods can, naturally, be invoked with different arguments. For example:

Keyword.Load(string description, SqlTransaction transaction)

--OR--

Keyword.Load(string description, string tag, SqlTransaction transaction)

Now, most methods in the framework that provide multiple overloads do so as follows:

A(int arg1)
A(int arg1, string arg2)
A(int arg1, string arg2, DateTime arg3)

Notably, the parameter order is consistent despite the overloads. However, I'd really like to emphasize the requirement for the user to pass in a connection or a transaction. Typically, these are the last arguments specified. But it seems to me that the best place to put them is parameter 0:

A(SqlTransaction transaction)
A(SqlTransaction transaction, int arg1)

Unfortunately, where this breaks down is in the declaration of the overload that takes neither a connection nor a transaction and creates one for you:

// These overloads create a connection, open it, and start a new transaction.
A()
A(int arg1)
A(int arg1, string arg2)
A(int arg1, string arg2)
A(int arg1, string arg2, DateTime arg3)

// These overloads require that the transaction be passed in, so that the method
// can take part in it.
A(SqlTransaction transaction)
A(SqlTransaction transaction, int arg1)
A(SqlTransaction transaction, int arg1, string arg2)
A(SqlTransaction transaction, int arg1, string arg2, DateTime arg3)

As you can see, it requires more overloads to get it right, but the emphasis on the transaction or connection just seems more clear to me.

If you were me, what path would you choose? Is there a design guideline that stipulates how scenarios like this should be handled? Is it too many overloads to deal with?

Answer 1

Straight from The Framework Design Guidelines:

Do be consistent in the ordering and naming of method parameters.

Edit:

If you don't want to follow the guideline, I would break the overloads into separate methods like so:

A()
A(int arg1)
A(int arg1, string arg2)
A(int arg1, string arg2)

and

AWithTransaction(SqlTransaction transaction)
AWithTransaction(SqlTransaction transaction, int arg1)
AWithTransaction(SqlTransaction transaction, int arg1, string arg2)
AWithTransaction(
    SqlTransaction transaction,
    int arg1,
    string arg2,
    DateTime arg3
)

In particular, I'd say

Keyword.Load(string description)
Keyword.Load(string description, string tag) 

and

Keyword.LoadWithTransaction(SqlTransaction transaction, string description)
Keyword.LoadWithTransaction(
    SqlTransaction transaction,
    string description,
    string tag
)