Software Design/Arrange parameters in a consistent order
Checklist questions:
- Parameters of similar functions are arranged in the same order?
- Parameters of functions that call each other are arranged in the same order?
Why
[edit | edit source]Consistency in the order of parameters is a form of structure of the code. Readers may learn the typical order of parameters for a set of similar functions and would know the meaning of arguments when they see a call to one of those functions without consulting to the function's definition or documentation.
Following this practice also reduces the probability of making copy-paste mistakes in code in programming languages with weak type systems when the parameters in similar functions have the same type. When developers copy-paste code with calls to some function with an intent to edit the copy-pasted code and replace the calls to the function with calls to some similar function, they may forget to rearrange the arguments (if the functions have different parameters' order). In fact, copy-pasting might be pointless when the order of parameter of the similar function is not consistent because in this situation copy-pasting would require too much of subsequent editing, and considering the risk of making mistakes.
Example
[edit | edit source]In I/O utility libraries and APIs, it's important to consistently arrange input and output parameters in the same order. In Guava's Files utility class, from parameters (inputs) to all utility methods go before to parameters (outputs). Therefore, when readers browse code that uses Guava's I/O utilities extensively and see a statement like Files.copy(file1, file2), they can assume that file1 is the source file and file2 is the destination file in the copy operation.