This post originated from an RSS feed registered with Agile Buzz by Keith Ray. Original Post: Code Smell: Long Parameter Plus + "Undocumented Language" Feed Title: MemoRanda Feed URL: http://homepage.mac.com/1/homepage404ErrorPage.html Feed Description: Keith Ray's notes to be remembered on agile software development, project management, oo programming, and other topics. Latest Agile Buzz Posts Latest Agile Buzz Posts by Keith Ray Latest Posts From MemoRanda

Wil Shipley describes the evil of Long Parameter List in some os Apple's APIS. But he is describing a variation on that code smell. It's kind of a combination of "Long Parameter List" with "Undocumented Language". I will bold-face that aspect of the problem in my quotes from that blog:

[...] There is usually one, giant, all-encompassing "setAttributes" function and one "getAttributes" function for setting and getting every value associated with a Carbon "object", which requires to you laboriously build up and then laboriously unparse huge, special parameter structures for even the simplest call. For example, see one of the newer (v6.4) QuickTime calls, for setting parameters on a FireWire video camera: VDIIDCSetFeatures(VideoDigitizerComponent ci, QTAtomContainer *container). That one call is used to set a HUGE number of parameters, which is "simple," except, oh, it takes eighty lines of code to prepare for that one call, and the parameters you can set are not actually documented in the documentation. [...]

[...] Carbon uses the same type, OSTypes [4-character constants] (eg, 'sit!'), extensively for everything: return codes, building parameter blocks (specifying what you want to do, how you want to do it), loading QuickTime components, etc., which means reading a function description doesn't actually give you enough information to know what to actually pass it. (Eg: "Pass it some combination of four-character constants. Good luck!") [...]

[...] (On a side note, sadly, the AppKit and Foundation team just announced they are moving AWAY from using enumerated types ... because they are worried that enumerated types could have unspecified sizes. But, seriously, Ali, this is totally broken -- enumerated types make reading and writing code MUCH easier, and they enforce sanity in switch() statements and if() comparisons. Please don't break this!) [...]

[...] For some reason some Carbon programmers think it's easier for them to add and remove APIs if they never commit to any particular functionality, so they use those giant anonymous set-get functions and then just have you build up a list of parameters yourself, with the idea being that it's a lot more flexible if they change the parameters out from under you than if they change the functions. [...]

[...] The fact that Apple had to write EIGHTY lines of example code to show how to set A SINGLE PARAMETER on SOME TYPES of cameras to its maximum value shows that THESE APIS ARE SERIOUSLY BROKEN. [...]

It goes on with examples from the KeyChain API. Check it out