Misc #15748
closed
[Documentation] Suggestion to adjust Object.html#method-i-instance_variable_set
Description
This is not hugely important but since it was mentioned on reddit for
whatever the intent (by surfordie), I'll add the issue here too.
The "issue" is a bit with the wording of:
https://ruby-doc.org/core-2.6.2/Object.html#method-i-instance_variable_set
"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."
I do not know who wrote this (not that it is important either), but I believe
it is:
a) not a correct statement as such
b) not necessary to word it like this.
I don't want to extensively explain why I think this is incorrect, because
that would take too long. I guess we all know that ruby does not "provide"
for "proper" (whatever that should even mean) encapsulation, largely because
ruby's philosophy and OOP is very different from other languages, such as java,
that assume that people have to be prevented from accessing/introspecting objects
at "run"time. Also see the .send() versus .public_send() debate - I myself only
make use of .send() and I think it's great. No clue what is frustrating about
what is great. :)
But anyway, I don't think I have to explain this more here; the primary thing is
that I think the explanation in the documentation could be changed. Rather than
assume that any encapsulation is "proper", and the alternative would be "improper",
by logical consequence (which I disagree with, too, just as I disagree with in that
other thread assuming that @1 @2 were to lead to "sloppy programming" - I don't
understand why people use such words), I propose to change the existing documentation
to somewhat that is worded and described a bit more "objectively".
I can not think of a great description but since it may be easier for others to follow,
I will start with an attempt at it - I will include the whole paragraph though:
"Sets the instance variable named by symbol to the given object. The variable
does not have to exist prior to this call and could thus be set through this
method. If the instance variable name is passed as a string, that string is
converted to a symbol. The method can be used as a generic setter."
This is not perfect either, I am aware of that; it's just meant as a starter.
Perhaps someone else has a better description - feel free to add that.
The primary goal is to get rid of conveying the opinion of whoever wrote it,
e. g. to get rid of the "frustrating" section altogether. Perhaps it could be
changed to point out that "encapsulation" is normally done through explicit setter
and getters, but my main goal here was to just find a wording that isn't quite as
hmm ... opinionated? I think it is better to not assume too much about the
intent of anyone using the method. I use it very happily sometimes and I
never understand how this could "frustrate" anyone - duck patching is a great
feature, or just adding/removing methods at "run"time too. We could get into the
philosophy of ruby too, but I just think that the documentation here may not
be ideal. Then again I also don't think it is that important either.
(I guess another slight problem is trying to keep the whole documentation
in a way as if it were written by a single individual who would write as
objectively as possible. I understand that this is not easily feasible of
course; just pointing it out. But someone else on reddit also mentioned that
it is not necessary to word it like this, to which I agreed so since everyone
seems too lazy to add an issue, I have to add one :P)
Updated by 
Updated by 
Updated by jeremyevans (Jeremy Evans)