From: shevegen@... Date: 2019-04-04T05:47:45+00:00 Subject: [ruby-core:92144] [Ruby trunk Misc#15748] [Documentation] Suggestion to adjust Object.html#method-i-instance_variable_set Issue #15748 has been reported by shevegen (Robert A. Heiler). ---------------------------------------- Misc #15748: [Documentation] Suggestion to adjust Object.html#method-i-instance_variable_set https://bugs.ruby-lang.org/issues/15748 * Author: shevegen (Robert A. Heiler) * Status: Open * Priority: Normal * Assignee: ---------------------------------------- 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) -- https://bugs.ruby-lang.org/ Unsubscribe: