0

During my years developing software I have most of the times tried to improve the readability of my code. As one example, I often try not to use boolean flag parameters of methods and I try to refactor them when I encounter it. I know that using boolean parameters can be a sign of a problem in the design but it is usually a simple refactor instead of refactoring entire classes and interfaces. Whether using boolean parameters is a good or bad thing is out of the scope of this question however.

Recently I have been told by colleagues that it is not necessary as IntellIJ will tell you the parameter name of a boolean when you use inlay hints. For example if you have the java method

public void sendEmail(Contact contact, boolean isCompany)

whenever you call this sendEmail method IntellIJ adds this little box saying that your boolean is isCompany (only when you use true or false directly in the method call I believe). My question is if it is acceptable to rely on your IDE for these kind of hints so you don't have to refactor or should you just refactor nonetheless if you don't like boolean parameters.

Glorfindel
  • 3,137
  • 6
  • 25
  • 33
pepijno
  • 129
  • 1
  • 2
    Does this answer your question? [How would you know if you've written readable and easily maintainable code?](https://softwareengineering.stackexchange.com/questions/141005/how-would-you-know-if-youve-written-readable-and-easily-maintainable-code) – gnat Mar 20 '20 at 09:08
  • I believe this is something that the team has to agree on. With that said, do you ever review code outside of the IDE? I have reviewed code in source control tools, for example, the IDE does not help me there. I would also care if we are talking of a public API or something used internally. If you change the order of bool parameters or flip their interpretation, consumer code might still compile without change, introducing bugs. Not with enums. Yes, that is not a problem if can refactor consumer code at the same time, however, you can't when it is a public API. – Theraot Mar 20 '20 at 09:28
  • Each boolean mean doubling the number of parameter permutations to test in your unit tests. I would say that if the tests are not comprehensive because it is too cumbersome, you've reached the breaking point. – Thorbjørn Ravn Andersen May 02 '20 at 11:52

3 Answers3

8

For the sake of my own sanity, when I say "method" I mean "method or constructor", since they both follow the same syntax in this scope.

I think you're conflating the boolean flag issue with an (un)named parameter readability argument. There are two separate issues which have some minor overlap (i.e. the unreadability of a long list of unnamed parameters), but they otherwise focus on very different problems/solutions.

The issue with boolean flags isn't method parameter readability, but rather that it's often used as a crutch allowing you to implement branching logic instead of implementing necessary abstractions.
As far as I can see, the issue you're dealing with here (i.e. unnamed method parameters) is independent of the type of the parameter in question.

Just to prove the point, in your given method signature, I can't know whether Contact is the sender or the recipient of the email either. I can make an educated guess that it's the recipient, but that doesn't change the fact that this is still a guess.

Unnamed method parameters will always depend on contextual inference, and this ranges from acceptable (can be reasonably inferred, e.g. SendEmail(Contact)) to unacceptable (cannot be reasonably inferred, e.g. SendEmail(bool,bool,bool,bool,bool,bool,bool)).

But that line of "reasonable" inference is subjective, and not everyone is going to see eye to eye on that.

If you see a method call which uses parameters you don't understand, and you want to understand them, the logical step is then to look up the method declaration.
This process is made nicer by some IDEs automatically looking it up for you (Rider even labels the parameters as if they were named parameters, which I do appreciate) or allowing you to click through to the declaration; but that doesn't mean that unnamed method parameters should logically be avoided at every single turn.

If unnamed method parameters were a no-go, then the language's syntax in regards to method signatures would need to be dramatically altered. You're trying to cover for something that the language doesn't just allow but it pretty much built on. That's a herculean task if ever I saw one.

If you do implement this "no unnamed parameter" approach, then that's a style guide, and style guides are contextual - generally scoped to your company. If your company bases their style guide on the IDE that they roll out to all their employees, that's perfectly okay.
It is possible that this benefit is lost when the company moves to a new IDE, but the IDE-reliant style guide could be significantly easier to implement and stick to. That's a cost/benefit analysis that is best left up to the business, there's no clear cut objectively superior (and universally correct) approach here.

Style guides and conventions are compromises between developers. If everyone innately agreed on the same style, we wouldn't need to create style guides as there'd be no style clashes to begin with.

Since your coworkers don't agree with your proposed style guide; that means it's not a good compromise. Their argument of relying on the IDE makes reasonable sense (just as much as yours does) - provided that this IDE is used across theb oard in your company, and it doesn't lead to architectural flaws in the code.

I'm no Java dev, but in the case of a language which has the option of using named parameters, that seems to be a reasonable compromise between you and your coworkers' opinions.
However, keep in mind that you're also going to have to draw the line on where you expect a named parameter and where you don't. If isCompany should be a named parameter, then should contact be named as well? Why not? What distinguishes the two? And so on...

Flater
  • 44,596
  • 8
  • 88
  • 122
  • 1
    Thanks, I never looked at it in a broader perspective like you mentioned. – pepijno Mar 20 '20 at 15:18
  • Java not having the parameter names in the actual call, makes this hard to read very quickly. Even if the IDE helps, you still need to ask it to show the additional information you need. – Thorbjørn Ravn Andersen May 02 '20 at 11:53
  • @ThorbjørnRavnAndersen: All IDEs I've worked with have had some kind of feeback, either by hovering over the method or a little tooltip that opens as you fill in the parameters of the method call. I can't conclusively speak for all possible IDEs but this feature is not that rare or unattainable. – Flater May 02 '20 at 21:04
  • @Flater Yes, you must "ask" for it by explicitly hovering the mouse or pressing a key combination. An IDE is much like a cockpit where all the information you need should be available at a glance (which in turn is why they use so much screen estate) which tooltips and hovers aren't. I believe that the Builder-pattern is a reasonable workaround for languages not supporting named parameters. – Thorbjørn Ravn Andersen May 02 '20 at 21:14
  • @ThorbjørnRavnAndersen: Your comment essentially boils down to forcing developers to either use the builder pattern or named parameters _at all times_. That is in no way indicative of common development practices at all. I point back to my answer: _"If unnamed method parameters were a no-go, then the language's syntax in regards to method signatures would need to be dramatically altered. You're trying to cover for something that the language doesn't just allow but is pretty much built on."_ – Flater May 02 '20 at 21:17
1

This:

Whether using boolean parameters is a good or bad thing is out of the scope of this question however.

Is incompatible with this:

My question is if it is acceptable to rely on your IDE for these kind of hints so you don't have to refactor or should you just refactor nonetheless if you don't like boolean parameters.

Because considering boolean parameters a bad thing is the only reason anyone could argue that you should always refactor them. Without this it's simply a matter of taste.

That said, writing code whose readability relies on a specific IDEs feature is rude to us mavericks that use something different. Like other IDEs, other text editors, visual difference tools, source control, and paper.

candied_orange
  • 102,279
  • 24
  • 197
  • 315
  • _"writing code whose readability relies on a specific IDEs feature is rude"_ To be fair here, I very much doubt that unnamed method parameters were implemented in the language (Java and others) _because_ IDEs would name them automatically, so I don't really think that your argument (while valid) particularly fits the case of unnamed method parameters. Not naming your method parameters isn't a matter of omitting something in favor of an IDE feature; not naming method parameters is the default language syntax to begin with. – Flater Mar 20 '20 at 10:44
0

An IDE can help assist with navigating through hard to read code, by it shouldn't be used as an excuse to actually write hard to read code.

You don't necessarily need refactoring here. All you really need to do is to explicitly specify the name of the argument when calling, many languages allow you to specify arguments by keyword instead of positionally:

sendEmail(contact, isCompany=True)

Another weaker alternative, is to set the argument name as an actual variable:

boolean isCompany = True
sendEmail(contact, isCompany)

but of course this has the drawback of potentially be misleading or incorrect if you refactor the method and rename the argument to something else.

Using typed enum is of course more desirable, but if you're stuck with the API that you have, the above are great alternatives.

Lie Ryan
  • 12,291
  • 1
  • 30
  • 41
  • The first option here is fine. As you point out, the second option is a time-bomb, because the parameters could be changed underneath you and then it only serves to make the problem worse. If I was just trying to make my own code easier to read (as the second example does), I would probably create a wrapper that eliminates the boolean parameter. This has the benefit of minimizing changes after a refactor as well. – Aaron M. Eshbach Mar 20 '20 at 14:49
  • Thanks for your suggestions. In kotlin named parameters can be used but unfortunately not in java. I personally prefer to split such methods into two methods, in this case sendEmailToCompany(contact) and sendEmailToPerson(contact), if the not-company option would be a person. – pepijno Mar 20 '20 at 15:16