Exclamation marks in method names

Sylvester_Keil · 14 November 2011 12:08

Dear all,

in a number of projects now, I've been (ab)using the convention of using exclamation marks at the end of method names somewhat and was therefore wondering about the current consensus in the community regarding the use of exclamation marks.

As outlined in the Matz/Flanagan book (also in Pickaxe and, I believe, I read about it the Best Practices book, too), the prevailing convention is to use exclamation marks for methods that should 'be used with caution'; common examples include mutators (when there is also a nonmutating variant), or methods that raise errors (when there are variants that fail 'silently' by returning a known good value or a default value). I have used exclamation marks in both these contexts, however, I've also come up with a different idiom recently, mainly in combination with predicates.

As we know, predicates (or predicate-like state) can often be accessed using methods ending with a question mark like #empty?, #nil? etc. Now, in cases where the predicate's state is determined solely by an attribute, I started using methods with exclamation marks to set the value. For example, consider a Date class that is supposed to handle uncertain dates:

d = Date.new
d.uncertain? #-> false
d.uncertain! #-> make date uncertain (instead of d.uncertain = true)
d.uncertain? #-> true
d.certain! #-> make date certain again

These methods are mutators, but they are not really dangerous (and there are no non mutating variants), so this usage is in violation with the naming convention. Nevertheless, I've grown quite fond of the symmetry (using both ? and ! for predicates), going so far as adding separate accessor generators (think attar_predicate). To make matters worse, I broke another convention: in Ruby, the exclamation mark mutators usually return self only if a mutation actually took place (nil otherwise), for example:

'U'.upcase! #-> nil

and are therefore not chainable. Because I wanted the predicate-setters to be chainable, I made them return self always. For instance, I had a Name class that printed names according to different formatting rules and I wanted to write things like:

name.sort_order!.to_s #-> set name to sort order formatting and convert to string

What do you think? Is it a terrible idea to break conventions like that and would you discourage or condone such usage? Also, I'd be curious to know if there were any other common conventions regarding the use of exclamation (and question) marks in method names?

Thanks!

Dave_Aronson1 · 14 November 2011 13:59

The general idea may be OK, but at least this particular case is a bit
jarring. Reading it, it looks like it sets the sort order to some
default (as opposed to name.sort_order!(Name::Sort_Lexical).to_s), and
converts *that sort order* to a string. IIUC what you're saying, it
would set the sort order, and convert the *name* to a string. The !
is a bit easy to miss.

I think what's irking me may be that the particular method name looks
(if you miss the !) like it's referring to *extracting* state rather
than *setting* it. name.set_sort_order!.to_s or
name.with_sort_order!.to_s might set more correct expectations -- at
least for me, as YM is almost guaranteed to V with something this
subjective.

-Dave

···

On Mon, Nov 14, 2011 at 07:08, Sylvester Keil <sylvester.keil@gmail.com> wrote:

Because I wanted the predicate-setters to be chainable, I made them return self
always. For instance, I had a Name class that printed names according to
different formatting rules and I wanted to write things like:

name.sort_order!.to_s #-> set name to sort order formatting and convert to string

--
LOOKING FOR WORK! What: Ruby (on/off Rails), Python, other modern languages.
Where: Northern Virginia, Washington DC (near Orange Line), and remote work.
See: davearonson.com (main) * codosaur.us (code) * dare2xl.com (excellence).
Specialization is for insects. (Heinlein) - Have Pun, Will Babble! (Aronson)

Robert_K1 · 14 November 2011 15:48

As outlined in the Matz/Flanagan book (also in Pickaxe and, I believe, I read about it the Best Practices book, too), the prevailing convention is to use exclamation marks for methods that should 'be used with caution'; common examples include mutators (when there is also a nonmutating variant), or methods that raise errors (when there are variants that fail 'silently' by returning a known good value or a default value). I have used exclamation marks in both these contexts, however, I've also come up with a different idiom recently, mainly in combination with predicates.

As we know, predicates (or predicate-like state) can often be accessed using methods ending with a question mark like #empty?, #nil? etc. Now, in cases where the predicate's state is determined solely by an attribute, I started using methods with exclamation marks to set the value. For example, consider a Date class that is supposed to handle uncertain dates:

d = Date.new
d.uncertain? #-> false
d.uncertain! #-> make date uncertain (instead of d.uncertain = true)
d.uncertain? #-> true
d.certain! #-> make date certain again

These methods are mutators, but they are not really dangerous (and there are no non mutating variants), so this usage is in violation with the naming convention. Nevertheless, I've grown quite fond of the symmetry (using both ? and ! for predicates), going so far as adding separate accessor generators (think attar_predicate).

That would be totally unobvious to me. I would rather expect (and be
looking for) a "=" sign somewhere to update the property / attribute.
That also has the advantage to treat all attributes alike when it
comes to updating. Not sure whether this in itself is such a big win
but the readability loss could be significant.

To make matters worse, I broke another convention: in Ruby, the exclamation mark mutators usually return self only if a mutation actually took place (nil otherwise), for example:

'U'.upcase! #-> nil

and are therefore not chainable. Because I wanted the predicate-setters to be chainable, I made them return self always. For instance, I had a Name class that printed names according to different formatting rules and I wanted to write things like:

Chainability is useful sometimes but I am in doubt whether it is such
a big asset. I'd probably judge convention higher.

name.sort_order!.to_s #-> set name to sort order formatting and convert to string

Doesn't look good to my eyes.

What do you think? Is it a terrible idea to break conventions like that and would you discourage or condone such usage?

Well, conventions are there to make our lives easier. If you break a
convention you need to compare the cost with the benefit. If you
intend to make the code from these projects public I'd say costs (=
negative impact) clearly outweigh benefits, because your convention is
not compatible with the "core convention". Even for purely internal
project I am not sure whether it is such a good idea. New people need
to get used to it (which is probably not too bad), but if you look at
other code you will constantly have to adjust your expectations (i.e.
foo! is chainable in your case while it is not generally in other
code) etc. I think the "beauty" to nicely align methods with
punctuation (!?) is not as important as the obstacles to reading and
writing code in an environment with your replacement convention. And:
if it ain't broken, don't fix it - could be read as "don't change
established conventions unless you have very good reasons".

Also, I'd be curious to know if there were any other common conventions regarding the use of exclamation (and question) marks in method names?

I am not aware of any other right now.

Kind regards

robert

···

On Mon, Nov 14, 2011 at 1:08 PM, Sylvester Keil <sylvester.keil@gmail.com> wrote:

--
remember.guy do |as, often| as.you_can - without end
http://blog.rubybestpractices.com/

Luca_Email · 29 December 2011 06:51

-----Messaggio originale-----

···

Da: Sylvester Keil [mailto:sylvester.keil@gmail.com]
Inviato: lunedì 14 novembre 2011 13:08
A: ruby-talk ML
Oggetto: Exclamation marks in method names

Dear all,

in a number of projects now, I've been (ab)using the convention of using
exclamation marks at the end of method names somewhat and was therefore
wondering about the current consensus in the community regarding the use of
exclamation marks.

As outlined in the Matz/Flanagan book (also in Pickaxe and, I believe, I
read about it the Best Practices book, too), the prevailing convention is to
use exclamation marks for methods that should 'be used with caution'; common
examples include mutators (when there is also a nonmutating variant), or
methods that raise errors (when there are variants that fail 'silently' by
returning a known good value or a default value). I have used exclamation
marks in both these contexts, however, I've also come up with a different
idiom recently, mainly in combination with predicates.

As we know, predicates (or predicate-like state) can often be accessed using
methods ending with a question mark like #empty?, #nil? etc. Now, in cases
where the predicate's state is determined solely by an attribute, I started
using methods with exclamation marks to set the value. For example, consider
a Date class that is supposed to handle uncertain dates:

d = Date.new
d.uncertain? #-> false
d.uncertain! #-> make date uncertain (instead of d.uncertain = true)
d.uncertain? #-> true d.certain! #-> make date certain again

These methods are mutators, but they are not really dangerous (and there are
no non mutating variants), so this usage is in violation with the naming
convention. Nevertheless, I've grown quite fond of the symmetry (using both
? and ! for predicates), going so far as adding separate accessor generators
(think attar_predicate). To make matters worse, I broke another convention:
in Ruby, the exclamation mark mutators usually return self only if a
mutation actually took place (nil otherwise), for example:

'U'.upcase! #-> nil

and are therefore not chainable. Because I wanted the predicate-setters to
be chainable, I made them return self always. For instance, I had a Name
class that printed names according to different formatting rules and I
wanted to write things like:

name.sort_order!.to_s #-> set name to sort order formatting and convert to
string

What do you think? Is it a terrible idea to break conventions like that and
would you discourage or condone such usage? Also, I'd be curious to know if
there were any other common conventions regarding the use of exclamation
(and question) marks in method names?

Thanks!

--
Caselle da 1GB, trasmetti allegati fino a 3GB e in piu' IMAP, POP3 e SMTP autenticato? GRATIS solo con Email.it http://www.email.it/f

Sponsor:
Riccione Hotel 3 stelle in centro: Pacchetto Capodanno mezza pensione, animazione bimbi, zona relax, parcheggio. Scopri l'offerta solo per oggi...
Clicca qui: http://adv.email.it/cgi-bin/foclick.cgi?mid982&d)-12

Sylvester_Keil · 14 November 2011 14:45

Because I wanted the predicate-setters to be chainable, I made them return self
always. For instance, I had a Name class that printed names according to
different formatting rules and I wanted to write things like:

name.sort_order!.to_s #-> set name to sort order formatting and convert to string

The general idea may be OK, but at least this particular case is a bit
jarring. Reading it, it looks like it sets the sort order to some
default (as opposed to name.sort_order!(Name::Sort_Lexical).to_s), and
converts *that sort order* to a string. IIUC what you're saying, it
would set the sort order, and convert the *name* to a string. The !
is a bit easy to miss.

Yes, the idea was that the !-method returns self, i.e., the name instance. (I realize now that this was a misleading example, because 'sort_order' was a clearly defined predicate in the original context and not akin to Ruby's #sort_by. Sorry for the confusion!)

I think what's irking me may be that the particular method name looks
(if you miss the !) like it's referring to *extracting* state rather
than *setting* it. name.set_sort_order!.to_s or
name.with_sort_order!.to_s might set more correct expectations -- at
least for me, as YM is almost guaranteed to V with something this
subjective.

Originally, my motivation was to have a symmetric setter for the ?-methods. Thus, something like:

parser.debug? #-> is debug flag true?
parser.debug! #-> set debug flag to true

That is to say, the !-method will always set the predicate to the state so that the corresponding ?-method will return true.

···

On Nov 14, 2011, at 2:59 PM, Dave Aronson wrote:

On Mon, Nov 14, 2011 at 07:08, Sylvester Keil <sylvester.keil@gmail.com> wrote:

Luca_Email · 29 December 2011 06:53

-----Messaggio originale-----

···

Da: Robert Klemme [mailto:shortcutter@googlemail.com]
Inviato: lunedì 14 novembre 2011 16:49
A: ruby-talk ML
Oggetto: Re: Exclamation marks in method names

On Mon, Nov 14, 2011 at 1:08 PM, Sylvester Keil <sylvester.keil@gmail.com> wrote:

As outlined in the Matz/Flanagan book (also in Pickaxe and, I believe, I

read about it the Best Practices book, too), the prevailing convention is to
use exclamation marks for methods that should 'be used with caution'; common
examples include mutators (when there is also a nonmutating variant), or
methods that raise errors (when there are variants that fail 'silently' by
returning a known good value or a default value). I have used exclamation
marks in both these contexts, however, I've also come up with a different
idiom recently, mainly in combination with predicates.

As we know, predicates (or predicate-like state) can often be accessed

using methods ending with a question mark like #empty?, #nil? etc. Now, in
cases where the predicate's state is determined solely by an attribute, I
started using methods with exclamation marks to set the value. For example,
consider a Date class that is supposed to handle uncertain dates:

d = Date.new
d.uncertain? #-> false
d.uncertain! #-> make date uncertain (instead of d.uncertain = true)
d.uncertain? #-> true d.certain! #-> make date certain again

These methods are mutators, but they are not really dangerous (and there

are no non mutating variants), so this usage is in violation with the naming
convention. Nevertheless, I've grown quite fond of the symmetry (using both
? and ! for predicates), going so far as adding separate accessor generators
(think attar_predicate).

That would be totally unobvious to me. I would rather expect (and be
looking for) a "=" sign somewhere to update the property / attribute.
That also has the advantage to treat all attributes alike when it comes to
updating. Not sure whether this in itself is such a big win but the
readability loss could be significant.

To make matters worse, I broke another convention: in Ruby, the

exclamation mark mutators usually return self only if a mutation actually
took place (nil otherwise), for example:

'U'.upcase! #-> nil

and are therefore not chainable. Because I wanted the predicate-setters to

be chainable, I made them return self always. For instance, I had a Name
class that printed names according to different formatting rules and I
wanted to write things like:

Chainability is useful sometimes but I am in doubt whether it is such a big
asset. I'd probably judge convention higher.

name.sort_order!.to_s #-> set name to sort order formatting and
convert to string

Doesn't look good to my eyes.

What do you think? Is it a terrible idea to break conventions like that

and would you discourage or condone such usage?

Well, conventions are there to make our lives easier. If you break a
convention you need to compare the cost with the benefit. If you intend to
make the code from these projects public I'd say costs (= negative impact)
clearly outweigh benefits, because your convention is not compatible with
the "core convention". Even for purely internal project I am not sure
whether it is such a good idea. New people need to get used to it (which is
probably not too bad), but if you look at other code you will constantly
have to adjust your expectations (i.e.
foo! is chainable in your case while it is not generally in other
code) etc. I think the "beauty" to nicely align methods with punctuation
(!?) is not as important as the obstacles to reading and writing code in an
environment with your replacement convention. And:
if it ain't broken, don't fix it - could be read as "don't change
established conventions unless you have very good reasons".

Also, I'd be curious to know if there were any other common conventions

regarding the use of exclamation (and question) marks in method names?