<html><head></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><br><div><div>On Oct 10, 2009, at 9:07 PM, Glyph Lefkowitz wrote:</div><div><br></div><blockquote type="cite"><div class="gmail_quote"><blockquote class="gmail_quote" style="border-left-width: 1px; border-left-style: solid; border-left-color: rgb(204, 204, 204); margin-top: 0pt; margin-right: 0pt; margin-bottom: 0pt; margin-left: 0.8ex; padding-left: 1ex; position: static; z-index: auto; "><div style=""><div><div>Much of the other code I'm using follows PEP-8 naming_conventions for methods and such whereas Twisted follows the Twisted Coding Standard which is a more javaCamelCase style convention.</div>
</div></div></blockquote><div><br>For what it's worth, the Twisted coding standard pre-dates PEP-8 (In fact, I think it might even predate the whole PEP process). <br></div></div></blockquote><br><blockquote type="cite"><div class="gmail_quote"><div>Also, Java did not invent the convention of camel-case names. My use of the convention in the early Twisted coding standard was a deliberate aping of Smalltalk's coding convention. I realize a lot more people have seen Java written this way than ST, but nevertheless ST was my inspiration for many of Twisted's conventions, coding-standard and otherwise.<br></div></div></blockquote><div><br></div><div>I understand. I refer to it as "Java" since that's more current. I think of it more as ST as well; I was there "back then." It's one of the things I really like about Twisted. I just kind of "get" it 'cause it makes sense from for a long time <sic>. </div><div><br></div><div>I don't particularly agree with, or like some things in PEP-8.</div><div><br></div><div>For example, I like to line things up "right" when organization can be indicated by spacing like (which will be mutilated by e-mail, but you know what I mean):</div><div><br></div><div>foo = (</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>("this value is long",<span class="Apple-tab-span" style="white-space:pre"> </span>"default"),</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>("short",<span class="Apple-tab-span" style="white-space:pre"> </span>"other"),</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>)</div><div><br></div><div>If it's a table, it should be laid out like a table, not all crooked and stuff. CamelCase is another issue. Why it should be OK in ClassNames but not OK in variable_names, since you have to hit the shift key to get the flippin' underscore anyway, has 'logic' that escapes me. "Inserting an extra, meaningless extra character, which requires using the Shift key, instead of the next letter, also with the shift key saves *thing*." </div><div><br></div><blockquote type="cite"><div class="gmail_quote"><blockquote class="gmail_quote" style="border-left-width: 1px; border-left-style: solid; border-left-color: rgb(204, 204, 204); margin-top: 0pt; margin-right: 0pt; margin-bottom: 0pt; margin-left: 0.8ex; padding-left: 1ex; position: static; z-index: auto; "><div style=""><div><div>That particular documentation refers to 'backwards compatible' functions using PEP-8 style attribute names while preferring the newer Twisted Coding Standard flavoured names.</div>
</div></div></blockquote></div><br>Yes, before code review was consistently applied throughout the codebase, we did have a few inconsistent names slip through. Since then we've tried to update them where we've found them so everything is consistently in one style.<br></blockquote><div><br></div><div>Also understood. That's the thing about writing stuff other people use; you've got to keep it working even when you're slapping your forehead about something you decided then that's now so _obviously_ better done another way.</div><div><br></div><blockquote type="cite">Making the right things show up in the right order in our API documentation is a constant challenge. If you have any ideas for emphasizing the correct (i.e. non-"backwards-compatibility") names, you might want to submit a patch to pydoctor and/or Twisted's docstrings.<br></blockquote><div><br></div><div>I actually took a quick look at pydoctor for the first time tonight. I'm wrestling with getting a doc set together from some code that's EpyDoc, some that's Sphinx, and some that's not there at all. </div><div><br></div><div>What I'd like is to use Sphinx, using all of EpyDoc's nice extensions to reStructuredText (e.g. the nice :Parameters: block stuff) so I'm looking to see if anyone's already done that work for Sphinx.</div><div><br></div><div>Meanwhile, vis-à-vis the Twisted docs, has there been any recent discussion about moving the Twisted docs to Sphinx? I found some doc discussions way back to 2002, nothing later than 2007/8-ish, but, as far as I know, there's not particular effort underway.</div><div><br></div><div>If Twisted could get documented with Sphinx, while adding anything Twisted needs that Sphinx doesn't have already, it would sure be nice...and would remove one more Twisted specific tool to maintain in the Twisted toolchain, while enhancing Sphinx at the same time.</div><div><br></div><div>I'm having to do the pydoctor vs. Sphinx vs. EpyDoc research anyway...I'll post it somewhere public and send a link/message to the list.</div><div><br></div><div>S</div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div></div></body></html>