Opened 16 months ago

#6568 enhancement new

Document policy regarding naming abbreviations, particularly with reference to RFCs

Reported by: tom.prince Owned by:
Priority: normal Milestone:
Component: core Keywords: documentation policy
Cc: Branch:
Author: Launchpad Bug:

Description

<kenaan> rwall r38721 branches/opt-record-5668-2/twisted/names M(dns.py test_dns.py): call the attribute rdlength rather than rdlen ...
<glyph> rwall: Why un-abbreviate only _half_ of the name? :)
<glyph> rwall: "rdataLength"?
<exarkun> recordDlength 
<tomprince> rdata is from the rfc, though.
<rwall> I was trying to be in keeping with existing RRHeader class
<exarkun> That's okay.  Our identifiers don't have to mirror the RFC.
<rwall> But yes I could make it clearer
<glyph> exarkun: All things being equal they should ...
<exarkun> Disagree
<glyph> exarkun: Of course all things in an RFC are not generally equal
<exarkun> Heh heh.
<exarkun> Yes, quite.  If there is an RFC that is easy to understand, then we should certainly adopt whatever we can from it.
<exarkun> The DNS RFCs do not seem to fall into this category.
<exarkun> Quick, is the "r" in "rdata" for "resource", "record", or "response"?
<glyph> exarkun: There's a cost to introducing new terminology, and it should be justified by improved comprehensibility.
<glyph> (And should always be documented by a reference to the RFC!)
<exarkun> There's minimal cost in expanding ambiguous acronyms
<exarkun> People who don't have the RFC memorized will be able to understand the expansion.  People who will also be able to understand it.
<glyph> exarkun: recordDataLength?
<exarkun> I agree that referencing the RFC terminology in the documentation for such identifiers is an entirely good idea

Change History (0)

Note: See TracTickets for help on using tickets.