This is ok:
void setUserIsDeadFlag(bool)This is not:
User findUserByName(string, bool)In the documentation, the parameters will have names and possibly further info pertaining to their use, but when I come to write code, I’m forced to add a comment explaining what the parameter is, so that I can read my own code later:
User bob = findUserByName("bob", false /* Don’t include dead users */);I can’t even trim my comment down, because the parameter name is something like include_dead_users. If I simply used the name in my comment, I’d make it look like I was passing false because I wanted to include dead users, which would be confusing:
User bob = findUserByName("bob", false /* include_dead_users */);The best solution to this problem (in all the languages I know) is to use enumerations, or at least constants. Here’s C++:
enum DeadUserInclusionPolicy { Include, Exclude };Before we start rushing off though, what’s wrong with the above? Let’s have a look at a method signature and a call:
void findUserByName(string name, DeadUserInclusionPolicy deadUserInclusionPolicy)
User bob = findUserByName("bob", Exclude);
namespace DeadUsers { enum InclusionPolicy { Include, Exclude } };
void findUserByName(string name, DeadUsers::InclusionPolicy policy)
User bob = findUserByName("bob", DeadUsers::Exclude);Finally we have readable ‘user’ code. In VB.NET and C# you don’t need to bother with a namespace and creative naming, because when you pass a value from an enumeration, you have to prefix it with the name of the enumeration, e.g. DeadUsersInclusionPolicy.Exclude
A large proportion of code that I come across has the boolean parameter problem. When I’m using C++ or C#, I add a comment to remind myself what I’m passing - and try to remember to update the comment if I change the value I pass. When I’m using VB.NET, I get to use a feature of the language to make things explicit: named parameters.
IO.Directory.Delete("c:\", Recursive:=True)
Dim Bob As New User(Name:="Bob", Surname:="Holness", Whereabouts:="Unknown")
