Related
To a partial in a HAML file, I am passing parameters whose value is long, or methods whose name is long, for example:
"Some quite long string"
quiteLongMethodNameHere(otherConstant)
To make them shorter, I wrapped them in a constant/variable:
- message = "Some quite long string"
- is_important = quiteLongMethodNameHere(otherConstant)
= render :some_component, msg: message, is_important: is_important
Is this a good practice? Or should I just put the value on the param without wrapping it inside variable/constant?
It's a case-by-case decision. You want to balance the sometimes-competing interests of clarity and conciseness. For me, it depends on the expressiveness of both forms. If the long method name is clear, precise, and expressive, then I would be less interested in using an intermediate variable to hold its result than if it were not.
In other cases where the long form is less expressive, I will often use intermediate variables as "living" documentation, even if they are used only on the next line of code. This more explicitly reveals your intention to the reader (who may someone else, or you at some future point in time).
I find intermediate variables are much better than code comments because code comments can more easily become obsolete, and having the clarification in code makes it available for debuggers, etc. The performance hit of creating an extra variable is minimal, and significant in only the most unusual of cases.
Another factor is if you are aggregating things (in arrays, hashes, etc.) that include these function calls and values, then using the intermediate variable makes the code neater, and possibly easier to understand, as you can customize the name to make the most sense in the context of that collection.
Regardless of the length of the string, it makes sense to assign it to a variable/constant, and not directly refer to it in a view file. If it is a text, it makes more sense to put it in a i18n file.
However, it is not good to do that in the main view file. If you are going to do it, do it in the controller file or a helper file.
I'm wondering what benefit discriminating between local and global variables provides. It seems to me that if everything were made a global variable, there would be a lot less confusion.
Wouldn't declaring everything a global variable result in fewer errors because one wouldn't mistakenly call a local variable in a global instance, thereby encountering fewer errors?
Where is my logic wrong on this?
Some of this boils down to good coding practices. Keeping variables local also means it becomes simpler to share code from one application to another without having to worry about code conflicts. While its simpler to make everything global, getting into the habit of only using global variables when you actually have to will force you to code more efficiently and will make your code more structured.
I think your key oversight is thinking that an error telling you a local variable doesn't exist is a bad thing - it isn't. You've made a mistake and ruby is telling you so. This type of mistake is usually easy to fix: you've misspelled something or you're using something that you forgot to create.
Global variables everywhere might remove those errors but they would replace them with a far harder set of errors to reason about: accidentally using a variable that another bit of code is using. Imagine if every time you called a function (one of your own or a standard library one or one from a gem) you had to check which global variables it might change (and which functions it called, since it might also change global variables) If you make a mistake then you might get an error message (if the class of the object in the variable changes enough) but often you would just silently get incorrect results (if the value of a variable you were using changes unexpectedly).
In general global variables are much harder to work with and people avoid them when possible.
If all variables are global, every line of code in every program (including those which haven't been written yet) written by every programmer on the planet (including those who haven't been born yet or are already dead) must universally, uniquely agree on the names of variables. If you use a variable name that someone else on a different continent two years from now will also use, both of your programs will break, when used together.
Edit: There appears to be at least two valid reasons why Smalltalkers do this (readability during message chaining and scoping issues) but perhaps the question can remain open longer to address general usage.
Original: For reasons I've long forgotten, I never use articles in my variable names. For instance:
aPerson, theCar, anObject
I guess I feel like articles dirty up the names with meaningless information. When I'd see a coworker's code using this convention, my blood pressure would tick up oh-so-slightly.
Recently I've started learning Smalltalk, mostly because I want to learn the language that Martin Fowler, Kent Beck, and so many other greats grew up on and loved.
I noticed, however, that Smalltalkers appear to widely use indefinite articles (a, an) in their variable names. A good example would be in the following Setter method:
name: aName address: anAddress.
self name: aName.
self address: anAddress
This has caused me to reconsider my position. If a community as greatly respected and influential as Smalltalkers has widely adopted articles in variable naming, maybe there's a good reason for it.
Do you use it? Why or why not?
This naming convention is one of the patterns in Kent Beck's book Smalltalk Best Practice Patterns. IMHO this book is a must-have even for non-smalltalkers, as it really helps naming things and writing self-documenting code. Plus it's probably one of the few pattern langages to exhibit Alexander's quality without a name.
Another good book on code patterns is Smalltalk with Style, which is available as a free PDF.
Generally, the convention is that instance variables and accessors use the bare noun, and parameters use the indefinite article plus either a role or a type, or a combination. Temporary variables can use bare nouns because they rarely duplicate the instance variable; alternatively, it's quite frequent to name them with more precision than just an indefinite article, in order to indicate their role in the control flow: eachFoo, nextFoo, randomChild...
It is in common use in Smalltalk as a typeless language because it hints the type of an argument in method call. The article itself signals that you are dealing with an instance of some object of specified class.
But remember that in Smalltalk the methods look differently, we use so called keyword messages and it this case the articles actually help the readability:
anAddressBook add: aPerson fromTownNamed: aString
I think I just found an answer. As Konrad Rudolph said, they use this convention because of a technical reason:
...this means it [method variable] cannot duplicate the name of an instance variable, a temporary variable defined in the interface, or another temporary variable.
-IBM Smalltalk Tutorial
Basically a local method variable cannot be named the same as an object/class variable. Coming from Java, I assumed a method's variables would be locally scoped, and you'd access the instance variables using something like:
self address
I still need to learn more about the method/local scoping in Smalltalk, but it appears they have no other choice; they must use a different variable name than the instance one, so anAddress is probably the simplest approach. Using just address results in:
Name is already defined ->address
if you have an instance variable address defined already...
I always felt the articles dirtied up the names with meaningless information.
Exactly. And this is all the reason necessary to drop articles: they clutter the code needlessly and provide no extra information.
I don’t know Smalltalk and can't talk about the reasons for “their” conventions but everywhere else, the above holds. There might be a simple technical reason behind the Smalltalk convention (such as ALL_CAPS in Ruby, which is a constant not only by convention but because of the language semantics).
I wobble back and forth on using this. I think that it depends on the ratio of C++ to Objective C in my projects at any given time. As for the basis and reasoning, Smalltalk popularized the notion of objects being "things". I think that it was Yourdon and Coad that strongly pushed describing classes in the first person. In Python it would be something like the following snippet. I really wish that I could remember enough SmallTalk to put together a "proper" example.
class Rectangle:
"""I am a rectangle. In other words, I am a polygon
of four sides and 90 degree vertices."""
def __init__(self, aPoint, anotherPoint):
"""Call me to create a new rectangle with the opposite
vertices defined by aPoint and anotherPoint."""
self.myFirstCorner = aPoint
self.myOtherCorner = anotherPoint
Overall, it is a conversational approach to program readability. Using articles in variable names was just one portion of the entire idiom. There was also an idiom surrounding the naming of parameters and message selectors IIRC. Something like:
aRect <- [Rectangle createFromPoint: startPoint
toPoint: otherPoint]
It was just another passing fad that still pops up every so often. Lately I have been noticing that member names like myHostName are popping up in C++ code as an alternative to m_hostName. I'm becoming more enamored with this usage which I think hearkens back to SmallTalk's idioms a little.
Never used, maybe because in my main language there are not any articles :P
Anyway i think that as long as variable's name is meaningful it's not important if there are articles or not, it's up to the coder's own preference.
Nope. I feel it is waste of characters space and erodes the readability of your code. I might use variations of the noun, for example Person vs People depending on the context. For example
ArrayList People = new ArrayList();
Person newPerson = new Person();
People.add(newPerson);
No I do not. I don't feel like it adds anything to the readability or maintainability of my code base and it does not distinguish the variable for me in any way.
The other downside is if you encourage articles in variable names, it's just a matter of time before someone does this in your code base.
var person = new Person();
var aPerson = GetSomeOtherPerson();
Where I work, the standard is to prefix all instance fields with "the-", local variables with "my-" and method parameters with "a-". I believe this came about because many developers were using text editors like vi instead of IDE's that can display different colors per scope.
In Java, I'd have to say I prefer it over writing setters where you dereference this.
Compare
public void setName(String name) {
this.name = name;
}
versus
public void setName(String aName) {
theName = aName;
}
The most important thing is to have a standard and for everyone to adhere to it.
No doubt, it's essential for understanding code to give member variables a prefix so that they can easily be distinguished from "normal" variables.
But what kind of prefix do you use?
I have been working on projects where we used m_ as prefix, on other projects we used an underscore only (which I personally don't like, because an underscore only is not demonstrative enough).
On another project we used a long prefix form, that also included the variable type. mul_ for example is the prefix of a member variable of type unsigned long.
Now let me know what kind of prefix you use (and please give a reason for it).
EDIT: Most of you seem to code without special prefixes for member variables! Does this depend on the language? From my experience, C++ code tends to use an underscore or m_ as a prefix for member variables. What about other languages?
No doubt, it's essential for understanding code to give member variables a prefix so that they can easily be distinguished from "normal" variables.
I dispute this claim. It's not the least bit necessary if you have half-decent syntax highlighting. A good IDE can let you write your code in readable English, and can show you the type and scope of a symbol other ways. Eclipse does a good job by highlighting declarations and uses of a symbol when the insertion point is on one of them.
Edit, thanks slim: A good syntax highlighter like Eclipse will also let you use bold or italic text, or change fonts altogether. For instance, I like italics for static things.
Another edit: Think of it this way; the type and scope of a variable are secondary information. It should be available and easy to find out, but not shouted at you. If you use prefixes like m_ or types like LPCSTR, that becomes noise, when you just want to read the primary information – the intent of the code.
Third edit: This applies regardless of language.
I do not use any prefix at all. If I run into danger of mixing up local variables or method parameters with class members, then either the method or the class is too long and benefits from splitting up.
This (arguably) not only makes the code more readable and somewhat "fluent", but most importantly encourages well structured classes and methods. In the end, it thus boils down to a completely different issue than the prefix or no-prefix dillema.
UPDATE: well, taste and preferences change, don't they.. I now use underscore as the prefix for member variables as it has proven to be beneficial in recognizing local and member variables in the long run. Especially new team members sometimes have hard time when the two are not easily recognizable.
None. I used to use underscore, but was talked out of it on a project where the others didn't like it, and haven't missed it. A decent IDE or a decent memory will tell you what's a member variable and what isn't. One of the developers on our project insists on putting "this." in front of every member variable, and we humour him when we're working on areas of code that are nominally "his".
Underscore only.
In my case, I use it because that's what the coding standards document says at my workplace. However, I cannot see the point of adding m_ or some horrible Hungarian thing at the beginning of the variable. The minimalist 'underscore only' keeps it readable.
It's more important to be consistent than anything, so pick something you and your teammates can agree upon and stick with it. And if the language you're coding in has a convention, you should try to stick to it. Nothing's more confusing than a code base that follows a prefixing rule inconsistently.
For c++, there's another reason to prefer m_ over _ besides the fact that _ sometimes prefixes compiler keywords. The m stands for member variable. This also gives you the ability disambiguate between locals and the other classes of variables, s_ for static and g_ for global (but of course don't use globals).
As for the comments that the IDE will always take care of you, is the IDE really the only way that you're looking at your code? Does your diff tool have the same level of quality for syntax hilighting as your IDE? What about your source control revision history tool? Do you never even cat a source file to the command line? Modern IDE's are fantastic efficiency tools, but code should be easy to read regardless of the context you're reading it in.
I prefer using this keyword.
That means this.data or this->data instead of some community-dependent naming.
Because:
with nowadays IDEs typing this. popups intellinsense
its obvious to everyone without knowing defined naming
BTW prefixing variables with letters to denote their type is outdated with good IDEs and reminds me of this Joel's article
We use m_ and then a slightly modified Simonyi notation, just like Rob says in a previous response. So, prefixing seems useful and m_ is not too intrusive and easily searched upon.
Why notation at all? And why not just follow (for .NET) the Microsoft notation recommendations which rely upon casing of names?
Latter question first: as pointed out, VB.NET is indifferent to casing. So are databases and (especially) DBAs. When I have to keep straight customerID and CustomerID (in, say, C#), it makes my brain hurt. So casing is a form of notation, but not a very effective one.
Prefix notation has value in several ways:
Increases the human comprehension of code without using the IDE. As in code review -- which I still find easiest to do on paper initially.
Ever write T-SQL or other RDBMS stored procs? Using prefix notation on database column names is REALLY helpful, especially for those of us who like using text editors for this sort of stuff.
Maybe in short, prefixing as a form of notation is useful because there are still development environments where smart IDEs are not available. Think about the IDE (a software tool) as allowing us some shortcuts (like intellisense typing), but not comprising the whole development environment.
An IDE is an Integrated Development Environment in the same way that a car is a Transportation Network: just one part of a larger system. I don't want to follow a "car" convention like staying on marked roads, when sometimes, its faster just to walk through a vacant lot. Relying on the IDE to track variable typing would be like needing the car's GPS to walk through the vacant lot. Better to have the knowledge (awkward though it may be to have "m_intCustomerID") in a portable form than to run back to the car for every small change of course.
That said, the m_ convention or the "this" convention are both readable. We like m_ because it is easily searched and still allows the variable typing to follow it. Agreed that a plain underscore is used by too many other framework code activities.
Using C#, I've moved from the 'm_'-prefix to just an underscore, since 'm_' is an heritage from C++.
The official Microsoft Guidelines tells you not to use any prefixes, and to use camel-case on private members and pascal-case on public members. The problem is that this collides with another guideline from the same source, which states that you should make all code compatible with all languages used in .NET. For instance, VB.NET doesn't make a difference between casings.
So just an underscore for me. This also makes it easy to access through IntelliSense, and external code only calling public members don't have to see the visually messy underscores.
Update: I don't think the C# "this."-prefix helps out the "Me." in VB, which will still see "Me.age" the same as "Me.Age".
It depends on which framework I'm using! If I'm writing MFC code then I use m_ and Hungarian notation. For other stuff (which tends to be STL/Boost) then I add an underscore suffix to all member variables and I don't bother with Hungarian notation.
MFC Class
class CFoo
{
private:
int m_nAge;
CString m_strAddress;
public:
int GetAge() const { return m_nAge; }
void SetAge(int n) { m_nAge = n; }
CString GetAddress() const { return m_strAddress;
void SetAddress(LPCTSTR lpsz) { m_strAddress = lpsz; }
};
STL Class
class foo
{
private:
int age_;
std::string address_;
public:
int age() const { return age_; }
void age(int a) { age_ = a; }
std::string address() const { return address_; }
void address(const std::string& str) { address_ = str; }
};
Now this may seem a bit odd - two different styles - but it works for me, and writing a lot of MFC code that doesn't use the same style as MFC itself just looks ugly.
I prefix member variables with 'm' and parameters (in the function) with 'p'. So code will look like:
class SomeClass {
private int mCount;
...
private void SomeFunction(string pVarName) {...}
}
I find that this quickly tells you the basic scope of any variable - if no prefix, then it's a local. Also, when reading a function you don't need to think about what's being passed in and what's just a local variable.
It really depends on the language.
I'm a C++ guy, and prefixing everything with underscore is a bit tricky. The language reserves stuff that begins with underscore for the implementation in some instances (depending on scope). There's also special treatment for double underscore, or underscore following by a capital letter. So I say just avoid that mess and simply choose some other prefix. 'm' is ok IMO. 'm_' is a bit much, but not terrible either. A matter of taste really.
But watch out for those _leadingUnderscores. You'll be surprised how many compiler and library internals are so named, and there's definitely room for accidents and mixup if you're not extremely careful. Just say no.
Most of the time, I use python. Python requires you to use self.foo in order to access the attribute foo of the instance of the current class. That way, the problem of confusing local variables, parameters and attributes of the instance you work on is solved.
Generally, I like this approach, even though I dislike being forced to do it. Thus, my ideal way to do thos is to not do it and use some form of attribute access on this or self in order to fetch the member variables. That way, I don't have to clutter the names with meta-data.
I'm weirdo and I prefix member variables with initials from the class name (which is camel-cased).
TGpHttpRequest = class(TOmniWorker)
strict private
hrHttpClient : THttpCli;
hrPageContents: string;
hrPassword : string;
hrPostData : string;
Most of the Delphi people just use F.
TGpHttpRequest = class(TOmniWorker)
strict private
FHttpClient : THttpCli;
FPageContents: string;
FPassword : string;
FPostData : string;
If the language supports the this or Me keyword, then use no prefix and instead use said keyword.
another trick is naming convention:
All member variables are named as usual, without any prefix (or 'this.' is it is usual to do so in the project)
But they will be easily differentiated from local variable because in my project, those local variables are always named:
aSomething: represents one object.
someManyThings: list of objects.
isAState or hasSomeThing: for boolean state.
Any variable which does not begin by 'a', 'some' or 'is/has' is a member variable.
Since VB.NET is not case-sensitive, I prefix my member variables with an underscore and camel case the rest of the name. I capitalize property names.
Dim _valueName As Integer
Public Property ValueName() As Integer
I'm with the people that don't use prefixes.
IDEs are so good nowadays, it's easy to find the information about a variable at a glance from syntax colouring, mouse-over tooltips and easy navigation to its definition.
This is on top of what you can get from the context of the variable and naming conventions (such as lowerCamelCase for local variables and private fields, UpperCamelCase for properties and methods etc) and things like "hasXXXX" and "isXX" for booleans.
I haven't used prefixes for years, but I did used to be a "this." prefix monster but I've gone off that unless absolutely necessary (thanks, Resharper).
A single _ used only as a visual indicator. (C#)
helps to group members with intellisense.
easier to spot the member variables when reading the code.
harder to hide a member variable with a local definition.
_ instead of this.
I use _ too instead of this. because is just shorter (4 characters less) and it's a good indicator of member variables. Besides, using this prefix you can avoid naming conflicts. Example:
public class Person {
private String _name;
public Person(String name) {
_name = name;
}
}
Compare it with this:
public class Person {
private String name;
public Person(String name) {
this.name = name;
}
}
I find the first example shorter and more clear.
It kinda depends what language you're working in.
In C# you can reference any member using the 'this' prefix, e.g. 'this.val', which means no prefixes are needed. VB has a similar capability with 'Me'.
In languages where there is a built-in notation for indicating member access I don't see the point in using a prefix. In other languages, I guess it makes sense to use whatever the commonly accepted convention is for that language.
Note that one of the benefits of using a built-in notation is that you can also use it when accessing properties and methods on the class without compromising your naming conventions for those (which is particularly important when accessing non-private members). The main reason for using any kind of indicator is as a flag that you are causing possible side effects in the class, so it's a good idea to have it when using other members, irrespective of whether they are a field/property/method/etc.
I use camel case and underscore like many here. I use the underscore because I work with C# and I've gotten used to avoiding the 'this' keyword in my constructors. I camel case method-scoped variants so the underscore reminds me what scope I'm working with at the time. Otherwise I don't think it matters as long as you're not trying to add unnecessary information that is already evident in code.
I've used to use m_ perfix in C++ but in C# I prefer just using camel case for the field and pascal case for its property.
private int fooBar;
public int FooBar
{
get { return fooBar; }
set { fooBar = value; }
}
I like m_ but as long as convention is used in the code base is used I'm cool with it.
Your mul_ example is heading towards Charles Simonyi's Apps Hungarian notation.
I prefer keeping things simple and that's why I like using m_ as the prefix.
Doing this makes it much easier to see where you have to go to see the original declaration.
I tend to use m_ in C++, but wouldn't mind to leave it away in Java or C#. And it depends on the coding standard. For legacy code that has a mixture of underscore and m_ I would refactor the code to one standard (given a reasonable code size)
I use #.
:D j/k -- but if does kind of depend on the language. If it has getters/setters, I'll usually put a _ in front of the private member variable and the getter/setter will have the same name without the _. Otherwise, I usually don't use any.
For my own projects I use _ as a postfix (as Martin York noted above, _ as a prefix is reserver by the C/C++ standard for compiler implementations) and i when working on Symbian projects.
In Java, one common convention is to preface member variables with "my" andUseCamelCaseForTheRestOfTheVariableName.
None if it's not necessary, single underscore otherwise. Applies for python.
If it is really necessary to prefix member variables, I would definitely prefer m_ to just an underscore. I find an underscore on its own reduces readability, and can be confused with C++ reserved words.
However, I do doubt that member variables need any special notation. Even ignoring IDE help, it isn't obvious why there would be confusion between what is a local and what is a member variable.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
A colleague of mine states that booleans as method arguments are not acceptable. They shall be replaced by enumerations. At first I did not see any benefit, but he gave me an example.
What's easier to understand?
file.writeData( data, true );
Or
enum WriteMode {
Append,
Overwrite
};
file.writeData( data, Append );
Now I got it! ;-)
This is definitely an example where an enumeration as second parameter makes the code much more readable.
So, what's your opinion on this topic?
Boolean's represent "yes/no" choices. If you want to represent a "yes/no", then use a boolean, it should be self-explanatory.
But if it's a choice between two options, neither of which is clearly yes or no, then an enum can sometimes be more readable.
Enums also allow for future modifications, where you now want a third choice (or more).
Use the one that best models your problem. In the example you give, the enum is a better choice. However, there would be other times when a boolean is better. Which makes more sense to you:
lock.setIsLocked(True);
or
enum LockState { Locked, Unlocked };
lock.setLockState(Locked);
In this case, I might choose the boolean option since I think it's quite clear and unambiguous, and I'm pretty sure my lock is not going to have more than two states. Still, the second choice is valid, but unnecessarily complicated, IMHO.
To me, neither using boolean nor enumeration is a good approach. Robert C. Martin captures this very clearly in his Clean Code Tip #12: Eliminate Boolean Arguments:
Boolean arguments loudly declare that the function does more than one thing. They are confusing and should be eliminated.
If a method does more than one thing, you should rather write two different methods, for example in your case: file.append(data) and file.overwrite(data).
Using an enumeration doesn't make things clearer. It doesn't change anything, it's still a flag argument.
Remember the question Adlai Stevenson posed to ambassador Zorin at the U.N. during the cuban missile crisis?
"You are in the courtroom of world
opinion right now, and you can answer
yes or no. You have denied that [the missiles]
exist, and I want to know whether I
have understood you correctly.... I am
prepared to wait for my answer until
hell freezes over, if that's your
decision."
If the flag you have in your method is of such a nature that you can pin it down to a binary decision, and that decision will never turn into a three-way or n-way decision, go for boolean. Indications: your flag is called isXXX.
Don't make it boolean in case of something that is a mode switch. There is always one more mode than you thought of when writing the method in the first place.
The one-more-mode dilemma has e.g. haunted Unix, where the possible permission modes a file or directory can have today result in weird double meanings of modes depending on file type, ownership etc.
There are two reasons I've run into this being a bad thing:
Because some people will write methods like:
ProcessBatch(true, false, false, true, false, false, true);
This is obviously bad because it's too easy to mix up parameters, and you have no idea by looking at it what you're specifying. Just one bool isn't too bad though.
Because controlling program flow by a simple yes/no branch might mean you have two entirely different functions that are wrapped up into one in an awkard way. For instance:
public void Write(bool toOptical);
Really, this should be two methods
public void WriteOptical();
public void WriteMagnetic();
because the code in these might be entirely different; they might have to do all sorts of different error handling and validation, or maybe even have to format the outgoing data differently. You can't tell that just by using Write() or even Write(Enum.Optical) (though of course you could have either of those methods just call internal methods WriteOptical/Mag if you want).
I guess it just depends. I wouldn't make too big of a deal about it except for #1.
I think you almost answered this yourself, I think the end aim is to make the code more readable, and in this case the enum did that, IMO its always best to look at the end aim rather than blanket rules, maybe think of it more as a guideline i.e. enums are often more readable in code than generic bools, ints etc but there will always be exceptions to the rule.
Enums are better but I wouldn't call boolean params as "unacceptable". Sometimes it's just easier to throw one little boolean in and move on (think private methods etc.)
Booleans may be OK in languages that have named parameters, like Python and Objective-C, since the name can explain what the parameter does:
file.writeData(data, overwrite=true)
or:
[file writeData:data overwrite:YES]
Enums have a definite benefit, but you should't just go replacing all your booleans with enums. There are many places where true/false is actually the best way to represent what is going on.
However, using them as method arguments is a bit suspect, simply because you can't see without digging into things what they are supposed to do, as they let you see what the true/false actually means
[Edit for the current state in 2022]
In modern C#, or other languages that support this, the nicest way to do it is with named arguments:
var worker = new BackgroundWorker(workerReportsProgress: true);
If your language doesn't allow for named arguments, then you may find properties to be a reasonable solution as well
[Original Answer from 2008 left for posterity]
Properties (especially with C#3 object initializers) or keyword arguments (a la ruby or python) are a much better way to go where you'd otherwise use a boolean argument.
C# example:
var worker = new BackgroundWorker { WorkerReportsProgress = true };
Ruby example
validates_presence_of :name, :allow_nil => true
Python example
connect_to_database( persistent=true )
The only thing I can think of where a boolean method argument is the right thing to do is in java, where you don't have either properties or keyword arguments. This is one of the reasons I hate java :-(
I would not agree that it is a good rule. Obviously, Enum makes for a better explicit or verbose code at some instances, but as a rule it seems way over reaching.
First let me take your example:
The programmers responsibility (and ability) to write good code is not really jeopardized by having a Boolean parameter. In your example the programmer could have written just as verbose code by writing:
dim append as boolean = true
file.writeData( data, append );
or I prefer more general
dim shouldAppend as boolean = true
file.writeData( data, shouldAppend );
Second:
The Enum example you gave is only "better" because you are passing a CONST. Most likely in most application at least some if not most of the time parameters that are passed to functions are VARIABLES. in which case my second example (giving variables with good names) is much better and Enum would have given you little benefits.
While it is true that in many cases enums are more readable and more extensible than booleans, an absolute rule that "booleans are not acceptable" is daft. It is inflexible and counter-productive - it does not leave room for human judgement. They're a fundamental built in type in most languages because they're useful - consider applying it to other built-in-types: saying for instance "never use an int as a parameter" would just be crazy.
This rule is just a question of style, not of potential for bugs or runtime performance. A better rule would be "prefer enums to booleans for reasons of readability".
Look at the .Net framework. Booleans are used as parameters on quite a few methods. The .Net API is not perfect, but I don't think that the use of boolean as parameters is a big problem. The tooltip always gives you the name of the parameter, and you can build this kind of guidance too - fill in your XML comments on the method parameters, they will come up in the tooltip.
I should also add that there is a case when you should clearly refactor booleans to an enumeration - when you have two or more booleans on your class, or in your method params, and not all states are valid (e.g. it's not valid to have them both set true).
For instance, if your class has properties like
public bool IsFoo
public bool IsBar
And it's an error to have both of them true at the same time, what you've actually got is three valid states, better expressed as something like:
enum FooBarType { IsFoo, IsBar, IsNeither };
Some rules that your colleague might be better adhering to are:
Don't be dogmatic with your design.
Choose what fits most appropriately for the users of your code.
Don't try to bash star-shaped pegs into every hole just because you like the shape this month!
A Boolean would only be acceptable if you do not intend to extend the functionality of the framework. The Enum is preferred because you can extend the enum and not break previous implementations of the function call.
The other advantage of the Enum is that is easier to read.
If the method asks a question such as:
KeepWritingData (DataAvailable());
where
bool DataAvailable()
{
return true; //data is ALWAYS available!
}
void KeepWritingData (bool keepGoing)
{
if (keepGoing)
{
...
}
}
boolean method arguments seem to make absolutely perfect sense.
It depends on the method. If the method does something that is very obviously a true/false thing then it is fine, e.g. below [though not I am not saying this is the best design for this method, it's just an example of where the usage is obvious].
CommentService.SetApprovalStatus(commentId, false);
However in most cases, such as the example you mention, it is better to use an enumeration. There are many examples in the .NET Framework itself where this convention is not followed, but that is because they introduced this design guideline fairly late on in the cycle.
It does make things a bit more explicit, but does start to massively extend the complexity of your interfaces - in a sheer boolean choice such as appending/overwriting it seems like overkill. If you need to add a further option (which I can't think of in this case), you can always perform a refactor (depending on the language)
Enums can certainly make the code more readable. There are still a few things to watch out for (in .net at least)
Because the underlying storage of an enum is an int, the default value will be zero, so you should make sure that 0 is a sensible default. (E.g. structs have all fields set to zero when created, so there's no way to specify a default other than 0. If you don't have a 0 value, you can't even test the enum without casting to int, which would be bad style.)
If your enum's are private to your code (never exposed publicly) then you can stop reading here.
If your enums are published in any way to external code and/or are saved outside of the program, consider numbering them explicitly. The compiler automatically numbers them from 0, but if you rearrange your enums without giving them values you can end up with defects.
I can legally write
WriteMode illegalButWorks = (WriteMode)1000000;
file.Write( data, illegalButWorks );
To combat this, any code that consumes an enum that you can't be certain of (e.g. public API) needs to check if the enum is valid. You do this via
if (!Enum.IsDefined(typeof(WriteMode), userValue))
throw new ArgumentException("userValue");
The only caveat of Enum.IsDefined is that it uses reflection and is slower. It also suffers a versioning issue. If you need to check the enum value often, you would be better off the following:
public static bool CheckWriteModeEnumValue(WriteMode writeMode)
{
switch( writeMode )
{
case WriteMode.Append:
case WriteMode.OverWrite:
break;
default:
Debug.Assert(false, "The WriteMode '" + writeMode + "' is not valid.");
return false;
}
return true;
}
The versioning issue is that old code may only know how to handle the 2 enums you have. If you add a third value, Enum.IsDefined will be true, but the old code can't necessarily handle it. Whoops.
There's even more fun you can do with [Flags] enums, and the validation code for that is slightly different.
I'll also note that for portability, you should use call ToString() on the enum, and use Enum.Parse() when reading them back in. Both ToString() and Enum.Parse() can handle [Flags] enum's as well, so there's no reason not to use them. Mind you, it's yet another pitfall, because now you can't even change the name of the enum without possibly breaking code.
So, sometimes you need to weigh all of the above in when you ask yourself Can I get away with just an bool?
IMHO it seems like an enum would be the obvious choice for any situation where more than two options are possible. But there definitely ARE situations where a boolean is all you need. In that case I would say that using an enum where a bool would work would be an example of using 7 words when 4 will do.
Booleans make sense when you have an obvious toggle which can only be one of two things (i.e. the state of a light bulb, on or off). Other than that, it's good to write it in such a way that it's obvious what you're passing - e.g. disk writes - unbuffered, line-buffered, or synchronous - should be passed as such. Even if you don't want to allow synchronous writes now (and so you're limited to two options), it's worth considering making them more verbose for the purposes of knowing what they do at first glance.
That said, you can also use False and True (boolean 0 and 1) and then if you need more values later, expand the function out to support user-defined values (say, 2 and 3), and your old 0/1 values will port over nicely, so your code ought not to break.
Sometimes it's just simpler to model different behaviour with overloads. To continue from your example would be:
file.appendData( data );
file.overwriteData( data );
This approach degrades if you have multiple parameters, each allowing a fixed set of options. For example, a method that opens a file might have several permutations of file mode (open/create), file access (read/write), sharing mode (none/read/write). The total number of configurations is equal to the Cartesian products of the individual options. Naturally in such cases multiple overloads are not appropriate.
Enums can, in some cases make code more readable, although validating the exact enum value in some languages (C# for example) can be difficult.
Often a boolean parameter is appended to the list of parameters as a new overload. One example in .NET is:
Enum.Parse(str);
Enum.Parse(str, true); // ignore case
The latter overload became available in a later version of the .NET framework than the first.
If you know that there will only ever be two choices, a boolean might be fine. Enums are extensible in a way that won't break old code, although old libraries might not support new enum values so versioning cannot be completely disregarded.
EDIT
In newer versions of C# it's possible to use named arguments which, IMO, can make calling code clearer in the same way that enums can. Using the same example as above:
Enum.Parse(str, ignoreCase: true);
Where I do agree that Enums are good way to go, in methods where you have 2 options (and just two options you can have readability without enum.)
e.g.
public void writeData(Stream data, boolean is_overwrite)
Love the Enums, but boolean is useful too.
This is a late entry on an old post, and it's so far down the page that nobody will ever read it, but since nobody has said it already....
An inline comment goes a long way to solving the unexpected bool problem. The original example is particularly heinous: imagine trying to name the variable in the function declearation! It'd be something like
void writeData( DataObject data, bool use_append_mode );
But, for the sake of example, let's say that's the declaration. Then, for an otherwise unexplained boolean argument, I put the variable name in an inline comment. Compare
file.writeData( data, true );
with
file.writeData( data, true /* use_append_mode */);
It really depends on the exact nature of the argument. If it is not a yes/no or true/false then a enum makes it more readable. But with an enum you need to check the argument or have acceptable default behaviour since undefined values of the underlying type can be passed.
The use of enums instead of booleans in your example does help make the method call more readable. However, this is a substitute for my favorite wish item in C#, named arguments in method calls. This syntax:
var v = CallMethod(pData = data, pFileMode = WriteMode, pIsDirty = true);
would be perfectly readable, and you could then do what a programmer should do, which is choose the most appropriate type for each parameter in the method without regard to how it looks in the IDE.
C# 3.0 allows named arguments in constructors. I don't know why they can't do this with methods as well.
Booleans values true/false only. So it is not clear what it represent. Enum can have meaningful name, e.g OVERWRITE, APPEND, etc. So enums are better.