How to choose between arguments and keys when defining a macro

Question

I would like to know if there are guidelines for package writers regarding the interface preferred for passing arguments to macros. Suppose I am writing a package for typesetting a titlepage. There are three main options:

1. LaTeX macro style \titlepage[color]{<title>}{<author>}
2. key-val style \titlepage{author=..., title=..., color=...}
3. "declarative" style \author{...}\title{...}\maketitlepage

Now, I prefer 2 and 3 to 1 because they do not require the user to remember the order of the arguments, they are more "literate" and they seem to be easier to extend.

Moreover, suppose I want to make my title page "themable". Would mixing keys for "data" (author/title) and "appearance" (color) be acceptable? Is key-val better suited for customisation rather than specification of content?

I think it is important to aim at uniform passing style to make adoption of packages smoother, but I could not find a clear guideline.

Answer 1

My rule of thumb is: if the number of possible arguments is small, and all but one or two are mandatory, I use standard arguments. If the number is large, or there are several optional arguments, key-value interface is probably better.