What's the correct and succinct way to refer to object attribute in (informal) description?

[Anonymous Monk]

When writing to someone, I think it's perfectly OK to say e.g. "hey, have a look at HTML::Element::tag() method". But what about attributes?

• '_tag' attribute of an instance of HTML::Element class? (too wordy)
• $HTML_Element_obj->{'_tag'}? (is actual class name clear from instance name?)
• HTML::Element->{'_tag'}? (short, but neither pseudocode nor correct Perl)

(Suppose it's blessed hashref but not HTML::Element as in example above and there are no getter/setter for an attribute.)

[choroba]

Peeking into attributes breaks encapsulation. It shouldn't be done under normal circumstances, so I'd consider it OK one needs to be wordy to tell others to do it.

With the new class feature, objects are no longer blessed hash references and their attributes (now called fields) can't be accessed without accessors, anyway.

#!/usr/bin/perl
use warnings;
use strict;
use feature qw{ say };
use 5.039.010;
use experimental 'class';

class My {
    field $x :param :reader;

}

my $o = 'My'->new(x => 10);
say $o->x;  # No other way.

Update: Fixed a typo, thanks LanX.

[LanX]

> Peeking into attributes breaks encapsulation

That's true, and I always defended the argument.

But from my (limited) experience with Python it seems they generally don't care.

Why is it so? Do they have a good a posteriori mechanism to override the attribute with accessor logic to fix potential problems?

Or do they just succeed by being less anal?

[choroba]

StackOverflow discussion about public attributes in Python.

[Fletch]

Python also has no true read only values ("constants" are named with all caps but there's nothing mechanically in the language itself stopping code from changing the values they point to) so my days of not respecting their design chops have certainly come to a middle.

[LanX]

I would go for a variation of
• $HTML_Element_obj->{'_tag'}
But consistently shorten HTML::Element to something like HE, to improve readability
• $HE_obj->{'_tag'}
Maybe clarifying that
• $HE_obj = HTML::Element->new(...)
NB: I was assuming that you have to document objects from multiple classes in the same doc.

Otherwise just go for $obj or $elem

[cavac]

If it's informal and not legally binding, make sure to add:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
have no meaning in this document.

SCNR