Sometimes (rarely), it seems that creating a function that takes a decent amount of parameters is the best route. However, when I do, I feel like I'm often choosing the ordering of the parameters at random. I usually go by "order of importance", with the most important parameter first.

Is there a better way to do this? Is there a "best practice" way of ordering parameters that enhances clarity?

Named parameters make this less than an issue. Python takes it to the extreme, look into it. A good example is in C# - the many ways to call MessageBox.Show. Look into that as well.
–
JobAug 16 '11 at 1:54

I usually go with these rules, though not always with the same precedence. I guess it's an automatic thought-process now, and I don't over-think it, except for public API design.

Selection Funnel

Semantics

Importance / Relevance

Frequency of Use

I/O Concerns

1. Semantics First

Especially in OOP, pick parameters based on their semantical significance for the action or message. The signature of a well-named method with a well-named parameter should:

feel natural to call,

be self-descriptive in terms of intent and behavior.

(For these reasons, sometimes using custom types or aliases instead of primitives might increase the expressiveness of your signature.)

2. Then Importance

The most "significant" parameter comes first (or next...)

3. Then Frequency

The frequency matters as well, especially in a language where you don't have named parameters but can have default values on positional parameters. That implies that the order of the parameters doesn't vary, and that obviously you cannot set the N + 1 parameters if you want to force the default value of the Nth parameter (except if your language has a concept of a place-holder parameter).

The good news for you is that usually, frequency relates to importance, so that goes hand in hand with the previous point. And then it's probably up to you to craft your API for it to have the appropriate semantics.

4. Let's Not Forget I/O

if your method/function takes some input and produces an output, and the latter is not to be "returned" (via a return statement) or "thrown" (using an exception system), then you're left with the option to pass values back to the caller using your other parameters (or the input parameter). That relates to semantics, and in most cases it will make sense to have the first parameters define the output, and the last parameters receive the output.

Additionally, an other approach to have less parameters and maximise semantics would be to use a functional approach, or to define a Builder pattern, so you can clearly stack up your inputs, define your outputs, and retrieve them when need be.

(Notice I don't mention global variables, because why would you use one, right?)

Some Things to consider

Usability

Most of the above will show naturally if you follow ZJR's advice: Use It!

Consider Refactoring

If you worry about parameter ordering, maybe this worry finds its root in the above and in the fact that your API is badly designed. If you have too many parameters, something can most probably be componentized/modularized and refactored.

Consider Performance

Keep in mind that some languages' implementations will incur very important impacts on your runtime memory management when using parameters. Hence the reason why many languages' style-books recommend to keep the parameter list simple and short. At 4 parameters max, for instance. I leave it as an exercise for you to figure out why.

Bevan's answer and mention of Clean Code's recommendations are definitely relevant as well!

I'd respectfully submit that worrying about parameter ordering is worrying about the wrong thing.

In Uncle Bob's book "Clean Code" he advocates, persuasively, that methods should never have more than two arguments - and most should have only one, if any. When this is the case, ordering is either obvious or unimportant.

In the rare cases where a method seems to require more information, introducing a parameter object is a good idea. Usually, I find this is the first step towards discovery of a new concept (object) that's key to my algorithm.

I definitely agree with you! My first statement was aimed to get at the point that this isn't a typical thing for me, haha. But in the case that I find I really do need to pass some parameters and it's not worth it to refactor the whole program, I wonder about ordering.
–
Casey PattonAug 16 '11 at 4:06

2

cough PHP cough. I'm sorry - you were saying something about not worrying about the order of parameters?
–
CraigeAug 16 '11 at 15:26

Won't you then just have a constructor for your parameter object that takes just as many arguments?
–
detlyMar 9 '12 at 2:02

No - because the parameter object can be "built up" over several statements in a way that's more readable.
–
BevanMar 9 '12 at 3:17

@Bevan: this is highly debatable. Building up objects this way means they can't be immutable anymore; keeping your objects immutable whenever possible however is another great way of increasing maintainability.
–
tdammersMar 9 '12 at 16:49

Sometimes the opposite is better, e.g., when there's always just one OUT argument and a variable number of in arguments, like in addAllTo(target, something1, something2).
–
maaartinusAug 16 '11 at 4:02

Though I follow the same rule, I try to avoid OUT parameters whenever possible, and most good programmers, too. So the number of functions where this recommendation actually helps the OP should be rather small.
–
Doc BrownFeb 9 at 19:02

@DocBrown You really shouldn't try to avoid good programmers, they can be useful to have around.
–
RyanfaeScotlandFeb 17 at 14:28

@RyanfaeScotland: damn, I should read my comments twice before posting them (or it least within the five minutes I can change them) ;-)
–
Doc BrownFeb 17 at 15:17

I've never seen a documented "best practice" regarding this particular topic, but my personal standard is to list them either in the order in which they will appear in the method they're being used for or if the method is more of a pass-through to a data layer I will list them in the order they would appear in the db schema or data layer methods.

Also, when there are multiple overloads of a method, I notice that the typical manner is to list them starting with parameters that are common to all (or most) of the methods with each different method being appended to the end for each method overload like:

I often follow the C/C++ convention of placing the const parameters first (that is, the parameters you pass in by value), and then those that you pass in by reference. This may not necessarily be the correct method of calling functions but, if you are interested in how each compiler handles parameters, have a look at the following links for the rules governing and/or the order that parameters are pushed onto the stack.

I usually just go with the "what looks less cyprtic" parameter ordering. The fewer times that I need to go to the method/function definition the better. And it's nice to have named parameters that are descriptive as to what they are used for, that way when the little tooltip pops up (VS) then it makes it even easier.

If you have lines and lines of parameters you may want to consider a different design. Step back and see how you can break that up into more functions/methods. Just an idea, but when I have a dozen parameters in my function it's almost always not a parameter issue, but a design issue.

Sometimes (rarely), it seems that creating a function that takes a decent amount of parameters is the best route.

Using several parameters is often a clear indicator, that you violate the SRP in this method. A method, which needs many parameters is unlikely to do only one thing. Excpetion may be a mathematical function or a configuration method, where indeed several parameters as such are needed. I would avoid multiple parameters as the devil avoids the holy water. The more parameters you use within a method, the higher the chance, that the method is (too) complex; the more complexity means: harder to maintain and that is less desirable.

However, when I do, I feel like I'm often choosing the ordering of the parameters at random. I usually go by "order of importance", with the most important parameter first.

In priniple you are choosing at random. Of course you might think paramter A is more relevant than parameter B; but that might not be the case for users of your API, who think B is the most relevant parameter. So even if you were attentive in choosing the ordering - for others it could seem random.

Is there a better way to do this? Is there a "best practice" way of ordering parameters that enhances clarity?

There are several ways out:

a) The trivial case: Do not use more than one parameter.

b) As you did not specify, what language you've chosen, there is the chance, that you chose a language with named parameters.
This is nice syntactic sugar which allows you to loosen the significance of the ordering of paramters: fn(name:"John Doe", age:36)

Not every language allows such niceties. So what then?

c) You could use a Dictionary/Hashmap/Associative Array as parameter:
e.g. Javascript would allow the following: fn({"name":"John Doe", age:36}) which is not far away from (b).

d) Of course if you work with a statically typed language like Java. you could use a Hashmap, but you would loose typeinformation (e.g. when working with HashMap<String, Object>) when parameters have different types (and need to cast).

The next logical step would be to pass an Object (if you are using Java) with appropriate properties or something more lightweight like a struct (if you write e.g. C# or C/C++).

I usually order them with required first, than by some combined measure of importancy and frequency of use according to a "feeling" (can be seen as ORDER BY required DESC, SOME_MAGIC_FEELING(importancy,frequency)) and not according to any specific practice.

However, as others have noted, I think the underlying problem that makes this an issue is using too many parameters (IMHO, anything >3 is too many) and that's the real problem that you should be addressing. There's an interesting post about that at rebecca murphey's blog.

I think that when you only have 1-3 arguments, the correct ordering is quite obvious and you just "feel" what's right.

Similar to @Wyatt Barnetts' answer, anything more than a few parameters or very explicit parameters for the method, I'd recommend passing an object instead. This is typically easier to update/maintain, clearer to read, and removes the necessity for worrying about ordering. Also, too many parameters for a method is a code smell and there are common refactoring patterns you can follow to help correct it.

Explicit example:

public int add(int left, int right)
{
return left + right;
}

Since this is a pretty clearly defined example and addition is commutative (order doesn't matter) then just go with it.