Parameter Dialogs
Allow programmers to enter parameter values (and object properties) via a dialog
Paul Lyons
IDEs typically give hints about the names of function parameters, but those hints are constrained by the textual nature of the code. There is not a lot of room for detailed information about the meaning or possible values for the parameters. The rectangular box in Figure 1 containing the words red, green, blue, alpha shows s typical hint, for the openGL function glClearColor(), as displayed by the PyCharm IDE.
Figure 1: Hints about the openGL function glClearColor, as displayed in the PyCharm IDE
In many cases, the number of parameters is large, their names are not self-explanatory, and there may be restrictions on the allowable values, either because there is a predefined set of constants that can be used, or because the parameters are not orthogonal – setting one parameter may restrict the possible values of another. In addition, parameters may be typed, so type information needs to be included in the hint.
I have been programming with OpenGl recently, which is full of function calls with large numbers (8 is not uncommon) of obscure parameters, and have run into this problem on many occasions.
Figure 2: Some functions have many parameters
Figure 3: A very similar function with a slightly different parameter set
Figure 2and Figure 3 show a pair of openGL functions. They are very similar in appearance (and intent), and they each have eight parameters, but the parameter lists differ slightly, and the names aren’t as meaningful as they might be (what’s the difference between x and xoffset, for example?). This is confusing, and the hints offer only a minimal amount of assistance.
Why not give programmers a richer way of specifying parameter values? If it were possible to enter parameter values via a dialog box, for example, it would be possible to include the name of the parameter, its type (in typed languages), a text-entry box for entry of constants/variables/expressions, drop-down boxes for parameters with a set of predefined values, hints about the meaning or usage of individual parameters. It would also be possible to display default values for parameters.
Figure 4: A possible structure for a dialog into which the programmer could enter the parameter values for the openGL function glCopyTexImage2D
Figure 4 shows a possible dialog for the openGL function glCopyTexImage2D. There are two drop-down boxes for parameters whose values are chosen from a predefined list. Most of the parameters have default values, but width and height have been left unspecified. The names, types, and descriptions of the parameters are shown.
This dialog obviously occupies significantly more space than the textual hints shown earlier, but it would only be present on the screen while a programmer was entering the values for a function’s parameters, so it would presumably not interfere too much with programmers’ ability to see and understand the rest of their code. In addition, the dialog in Figure 4 is particularly large because, in order to emphasise the hassles associated with assigning values to parameters, I chose a function that illustrates the problems particularly well - and it has eight parameters.
A similar dialog could be adopted for assigning values to the properties of an object; it is frequently necessary to assign a whole list of values to object properties, and it would be helpful if the IDE made it easy to see those properties, their types, and so on, in a similar fashion to function parameters.
A further improvement might be to allow programmers to add their own hints for parameters; parameters names are not always self-explanatory, and official definitions are often jargon-ridden, so it may help a programmer to add her or his own explanation for the meaning or usage of the parameter or object property. Furthermore, if users were able to share their descriptions publicly, then the writers of libraries could be spared the burden of creating a whole new set of documentation (albeit one that would possibly be more useful and more widely used than current help systems). And the number of repeat queries about simple problems from newbies on sites like stackoverflow.com might decrease[1].
Note that the preceding description does not include any suggestions about how the programmer would trigger display of the dialog. It is likely that power programmers would find it tedious to have to create all parameter lists via such a mechanism, so the programmer would need to be in control of whether or not the dialog was displayed – or there would need to be an automatic way of displaying it only when required. Current IDEs typically display a hint when the programmer types a known function name followed by a left parenthesis, and highlight a parameter name each time the programmer types a value inside the parameter list.
The dialog would not interfere too much with the programmer’s flow if the display of a (non-modal) dialog box were triggered by the same mechanism (i.e., function name, followed by a left parenthesis), so that the programmer could continue typing into the textual representation of the program, (which would update the contents of the dialog) or could jump into the dialog box (which would update the textual representation of the program). In addition, commas[2] in the dialog box would tab to the next text entry field, so that the distinction between entering parameter values via the dialog and via conventional text entry would be minimal.
Alternatively, programmers could display the dialog using an explicit trigger. Again, this would only operate when the programmer had typed a function name followed by a left parenthesis. Another left parenthesis could be used, though this would conflict with complex first parameters that started with a parenthesised subexpression, such as sin((X+3)*2). Or maybe a function key.
On the whole I feel that the automatic mechanism with, say, a half-second delay to allow power users to program without interferenceis preferable. It would not require beginning programmers to have to learn another arbitrary keystroke, it would allow beginning programmers to transit to power programmers relatively seamlessly, and it would allow for the fact that even power programmers don’t always know the parameter lists and property lists of all the available functions and classes.
Creating function prototypes is something that could (should?) use the same feature. A function prototype contains the same information that goes into the proposed dialog (except for the parameter descriptions).
Project: implement a testbed that could be used to experiment with this idea. Identify (and solve) problems associated with this idea.
It looks as though SQL Server 2016 does something similar to what I’m suggesting. It has a Set Parameter Value Dialog Box to which the following description[3] applies
[1] Note that I personally have no problem with such queries; they are frequently helpful. However, a significant number of queries on such sites provoke responses whose subtext is, “Everyone knows how to do that. Stop bothering us with stupid questions,” and it seems to me that the number of such responses could be reduced if programmers could more easily learn about how to use functions.
[2] except in quoted strings
[3] (downloaded 14/07/2015)