kotlin-style-guide
kotlin-style-guide copied to clipboard
Kotlin
Boolean parameters on a call site
Boolean parameters in a multi-parameter function (boolean flags) must be marked on a call site to clarify their meaning. In for Kotlin functions use named parameters. For Java functions use inline comments since named parameters are prohibited (v1.0):
// Kotlin
fun String?.equals(other: String?, ignoreCase: Boolean = false): Boolean {}
// Usage:
"abc".equals("ABC", ignoreCase = true)
or
// Java
boolean regionMatches(boolean ignoreCase, int toffset, String other, int ooffset, int len) {}
// Kotlin usage:
"abcd".regionMatches(/*ignoreCase*/ true, 1, "BC", 0, 2)
This is not applicable when the boolean parameter is not a boolean flag (e.i. it's the only non-optional parameter or it's a boolean vararg):
// Java
valueOf(boolean b)
// Kotlin usage:
String.valueOf(true)
IMO this one should be mandatory. Not only there should be an IDE intention to add the clarification comments, but the auto formatter should add them on its own.
I don't believe that people would appreciate the auto-formatter adding any kind of comments to their code, unless they've explicitly asked for that.
Yes I understand formatters don't usually do that. The reason for my opinion is that it's super lame to add those by hands
That is definitely true. :) One option is to make an inspection ("Boolean parameter passed without specifying argument name") and to allow running it through Code Cleanup.
@voddan actually it's applicable not just for booleans, but for all literals. For example, here is a function call that you wrote 2.5 mo ago.
"abcd".regionMatches(/*ignoreCase*/ true, 1, "BC", 0, 2)
Can you remember what all these values mean without peeking into function's declaration?
@dstd The idea was to actively enforce naming for boolean flags, and leave the rest to the developer. Non-boolean parameters are usually self-explanatory and follow conventions, while bools are always a mystery.
An example of multiple Double constants that do not necessarily require naming because they follow a common convention:
Rectangle(10.0, 10.0, 100.0, 5.0)
On the other hand the developer is free to name them:
Rectangle(x = 10.0, y = 10.0, w = 100.0, h = 5.0)
Ideally, there should be language feature so that one can mark a parameter as "always use by name". This puts the decision into the hands of a person who designs API. There is already a requirement that parameters after vargas can be invoked by name only, by the way. However, there is also an interop question, e.g. in how one should call existing Java APIs? Booleans are special, indeed. It seems logical, that interop layer shall implicitly mark all Java functions with boolean parameters as "always use by name" if the original name is available in the class file.
Since IJ 2016.3 has a feature of "Parameter hints", I wonder if the concept of this thread become absolute.
I think that the example @voddan gave is a perfect example why this should be applicable to literals, not just booleans.
Rectangle(10.0, 10.0, 100.0, 5.0) is ambiguous. Where is the top-right vertex of that Rectangle? Is it at (100, 10)? Or (110, 10)? I thought it was the former, because some rectangle APIs take 4 params that are the absolute coordinates of the 4 edges, but it turns out that the 3rd and 4th parameters in this API are width and height offset from the top and left edges. You can only know this if you use named params.
@kevinmost Luckily such conventions as Double parameters of a region are consistent across a framework or a library. That means that if review an old (Swing?) project, you are unlikely to face a lot of problems, since this Swing convention (x, y, w, h) would pop up all other the code.
Personally I prefer Rectangle(10.0, 10.0, /*width*/ 100.0, /*height*/ 5.0), since that non-ambiguously signal what is what. I would prefer that the formatter did not force me to do anything here, since it is obviously incapable of determining what I want (except for @elizarov 's idea, which has its issues)