Ticket #6568 enhancement new
Opened 9 months ago
Document policy regarding naming abbreviations, particularly with reference to RFCs
|Reported by:||tom.prince||Owned by:|
<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
Note: See TracTickets for help on using tickets.