Project

General

Profile

Actions

Misc #15265

closed

Documentation for `Object#instance_variable_set` is inaccurate and pejorative

Added by CaryInVictoria (Cary Swoveland) over 5 years ago. Updated almost 4 years ago.

Status:
Closed
Assignee:
-
[ruby-core:89594]

Description

The v2.5.1 documentation for this method states, in part, "Sets the instance variable named by symbol to the given object, thereby frustrating the efforts of the class's author to attempt to provide proper encapsulation." The phrase beginning, "thereby..." is not necessarily true and seems to mock the fact that the method has been provided to us for its use. Suppose, for example, that the author has provided getters and setters for all of an object's instance variables, so there is no encapsulation issue. There still may be situations where this method (and Object#instance_variable_get) could be used to advantage. One is where we want to perform certain operations on all instances variables. Where it is possible to write, <instance>.instance_variables.each { |v| f(v) }, this has several advantages over manipulating the instance variables individually: it requires less code, debugging and testing is simpler, there is less chance of introducing a bug; and adding, removing or renaming instance variables may not require f(v) to be changed.


Related issues 1 (0 open1 closed)

Related to Ruby master - Misc #15748: [Documentation] Suggestion to adjust Object.html#method-i-instance_variable_setClosedActions
Actions #1

Updated by CaryInVictoria (Cary Swoveland) over 5 years ago

  • Description updated (diff)
Actions #2

Updated by CaryInVictoria (Cary Swoveland) over 5 years ago

  • Description updated (diff)

Updated by shevegen (Robert A. Heiler) over 5 years ago

Yes I agree. That phrasing is not necessary.

There is more than one way to do many things in ruby. A good example is .send()
versus .public_send(). I think matz's philosophy is closer towards .send() (which
makes more sense to me and I do not use .public_send() myself; plus .send() was
there much earlier than .public_send(), which was added at a later time), but I
think it was added to provide those who want "strong(er)" encapsulation with some
more specific APIs.

Even though I think the distinction between public/private/protected does not
make that much sense in ruby to begin with, due to ruby's (awesome) flexibility
anyway. Different languages pursue different OOP models.

Anyway, I concur with you in regards to the documentation about instance_variable_set.
I assume that others among the core team may also agree with you here (I think, but of
course I can not speak for them). The only thing left to do may be to suggest an
alternative wording that could be used. What would you suggest? Only dropping the
part "thereby frustrating ..." or a complete rewording?

Updated by mame (Yusuke Endoh) over 5 years ago

Indeed, it looks a very subjective view of the author (Dave Thomas). Though, I can't understand its subtlety because I'm not a native speaker.

It might have been just a joke, but anyway, more or less, he wanted to say that "do not use this method easily", I guess. This kind of meta programming feature can shoot yourself in the foot. So, I think that rephrasing is better than just dropping.

Updated by duerst (Martin Dürst) over 5 years ago

mame (Yusuke Endoh) wrote:

Indeed, it looks a very subjective view of the author (Dave Thomas). Though, I can't understand its subtlety because I'm not a native speaker.

It might have been just a joke, but anyway, more or less, he wanted to say that "do not use this method easily", I guess. This kind of meta programming feature can shoot yourself in the foot. So, I think that rephrasing is better than just dropping.

I agree with Yusuke here. The wording is slightly odd for documentation, so I'd reword along the following lines:

"Sets the instance variable named by symbol to the given object. This may circumvent the the encapsulation intended by the author of the class, so it should be used with care."

Actions #6

Updated by mame (Yusuke Endoh) almost 5 years ago

  • Related to Misc #15748: [Documentation] Suggestion to adjust Object.html#method-i-instance_variable_set added
Actions #7

Updated by jeremyevans (Jeremy Evans) almost 4 years ago

  • Status changed from Open to Closed

Applied in changeset git|573e8d7736c84149ae298f4a8ed532525b6645d0.


Change language used in instance_variable_set documentation [ci skip]

This uses less harsh language recommended by duerst.

Fixes [Misc #15265]
Fixes [Misc #15748]

Actions

Also available in: Atom PDF

Like0
Like0Like0Like0Like0Like0Like0Like0