How Many Parameters Should a Good Method Have?

Hi,

Methods and call to methods, like any other code you write, need to be reviewed and tested.
When you type in studio you will see a tool-tip with the current parameter position in bold. 

Some times, when you need to pass a huge number of parameters to a function/method you might put there in a key=value array and simply pass this by ref.  

It's really a matter of taste.

If you don't like the long list of params (especially with lousy documented methods) you can

#1) use 1 single param and pass a local array byRef .  and decode it yourself eg:

or

#2) use the traditional style you may know from Caché I/O Device Guide  having also just 1 parameter

I personally prefer #2) as it gives you an embedded doc on your intentions.

Look at this

Class User.Test
{

ClassMethod Test(Args...)
{
  ZWRITE Args
}

ClassMethod Test2(Arg1, Arg2, Arg3, Arg4, Arg5, Arg6, Arg7, Arg8)
{
  ZWRITE Arg1
  ZWRITE Arg2
  ZWRITE Arg3
  ZWRITE Arg4
  ZWRITE Arg5
  ZWRITE Arg6
  ZWRITE Arg7
  ZWRITE Arg8
}

}

and let's call it

USER>do ##class(Test).Test(1,2,,,,,,8)  
Args=8
Args(1)=1
Args(2)=2
Args(8)=8

and second method

USER>do ##class(Test).Test2(1,2,,,,,,8) 
Arg1=1
Arg2=2
Arg8=8

And another way 

USER>set args=8 ;just the number of the latest one                      

USER>set args(8)="test"

and calls

USER>do ##class(Test).Test(args...)
Args=8
Args(8)="test"

USER>do ##class(Test).Test2(args...)
Arg8="test"

Good question. Given our long history, we have a fair number of utility methods whose signatures grew organically and for which backwards compatibility goals have prevented us from doing significant cleanup. We're now in the process of reviewing the SQL utility methods and for the ones that really need as many parameters, are considering the use of an options string (aka compile flags), as is being used by some more modern infrastructure such as the work queue manager and/or just making separate specific methods rather than super-generic 10-argument ones. While we're at it, I'm eager to read suggestions or feedback on how others developing utility functions are dealing with this.

Some thoughts.

1. Do not use Hungarian notation.

2. Do not use ByRef params/dynamic objects/$lists/args... as an arguments. There are two exceptions:  you don't know the number of arguments or there's more than 10 arguments.

3. Method should not parse arguments, only validate arguments. If caller passed invalid input it's caller problem. Fail fast.

4. Mandatory arguments go first.

5. If several methods have similar signatures, the order of arguments should be the same.

6. Same logical arguments in different methods should have the same names.

7. Arguments should be consistent. If you pass primitives, pass primitives everywhere. If you pass dynamic objects, pass them everywhere.

8. Return types should also be consistent.

9. If it's object methods and you pass the same optional arguments in several methods extract these arguments as a property.
 

Hi. The "clean code" people would recommend just one parameter max, and better would be none! But I think that's going a bit far, and agree that 3, or maybe 4, maximum should be aimed for to keep things easy to understand when reading, though there may be exceptions.

The array passing is a good idea to reduce the number for normal routines, but I think the ideal for classes is using objects. If you are truly embracing objects, and self-documenting code, then new classes are usually needed and what used to be parameters become the setting of properties, like this:

S table=##class(CMT.UI.Table).%New()
S table.TopLine=10,table.BottomLine=21
S table.HeaderFormat="Underline"
D table.DefineQuery("CMT.UI.PatchSite:MyList")
D table.AddColumn(3,,"BOLD")
...etc.

D table.Display()

It works well in some cases, but I have to admit that there is a tendency for the number of classes to get a bit silly if you take it to the extreme. Sometimes simple code is best.  :-)     / Mike

UPDATE: Oh, this technique has been mentioned already, either way this sample shows why to use it.

That's gonna be quite the bump, but it's worth mentioning. Since the adoption of %Dynamic classes, you can now provide a JSON object to methods, this way you get a syntax that ressembles POJOs (Plain Old JavaScript Objects):

ClassMethod GreetAndAsk(data As %DynamicObject) As %String
{
    return $$$FormatText("Hello %1! %2", data.name, data.message)
}

// Omitted for brevity.
write ..GreatAndAsk({
  "name": "Rubens",
  "message": "How are you?"
})

This is really useful if you must provide a method with several parameters that have some sort of link between them, here's a real use-case:

/// This method implements a full-sized configuration on how to handle multipart uploads.
ClassMethod TestPOSTMultipartFileUpload() As %Status
{
  set location = %frontier.Data.Workspace_"/fixtures/uploads/multiple"
  set destination = (location_"/:KEY/:FILE_NAME:EXTENSION")

  // 512 KB
  set maxFileSize = (1024**2/0.5)

  return %frontier.Files.Upload({
    "hooks": {
      "onItemUploadSuccess": "Frontier.UnitTest.Router:WriteResultToProcessGlobal",
      "onItemUploadError": "Frontier.UnitTest.Router:WriteErrorToProcessGlobal",
      "onComplete": "Frontier.UnitTest.Router:WriteResultSummaryToProcessGlobal"
    },
    "filters": {
      "verbose": true,
      "maxFileSize": { "value": (maxFileSize), "errorTemplate": "The file :FILE_NAME exceeded the max of :VALUE bytes." },
      "extensions": ["cls", "md", "txt", "pdf"]
    },
    "destinations": {
      "file_a": { "path": (destination) },
      "file_b": { "path": (destination) },
      "file_c": { "path": (destination), "optional": true },
      "file_d": { "path": (destination), "optional": true },
      "files": {
        "path": (location_"/files/:INDEX/:FILE_NAME:EXTENSION"),
        "slots": 3,
        "filters": { "maxFileSize": 500000000 }
      }
    }
  })
}

The only real solution is support of named arguments (like Python)

They are on my ISC wish-list for many years ;-)

To incorporate in COS-native is a challenge, but in Methods it shouldn't be so hard.