Opened 14 years ago

Closed 11 years ago

#2217 defect closed fixed (fixed)

Coding Standard is fairly crusty

Reported by: Jonathan Lange Owned by:
Priority: normal Milestone:
Component: core Keywords: documentation, policy
Cc: Thijs Triemstra Branch: branches/crusty-standard-2217
branch-diff, diff-cov, branch-cov, buildbot
Author: thijs

Description

The coding standard is quite old and could use an overall edit. Some things

  • Don't recommend testing, refer to uqds
  • Don't use "I"
  • I certainly don't write code with a thesaurus open.
  • Twisted doesn't have any databases
  • "UNDOCUMENTED" as a docstring is never used

I'm going to just do this and then put it up for review.

Change History (11)

comment:1 Changed 14 years ago by Cory Dodt

I've always regarded the bit about dictionary and thesaurus as being metaphorical, not literal, and I think the message is still germane. Unless you wish to refer the user to make bookmarks for dictionary.com and thesaurus.com http://dictionary.reference.com/search?q=%s and http://thesaurus.reference.com/search?config=roget&q=%s I don't think that section needs updating.

comment:2 Changed 12 years ago by Thijs Triemstra

Cc: Thijs Triemstra added
Owner: changed from Jonathan Lange to Thijs Triemstra
Status: newassigned

comment:4 Changed 11 years ago by Thijs Triemstra

Author: thijs
Branch: branches/crusty-standard-2217

(In [26443]) Branching to 'crusty-standard-2217'

comment:5 in reply to:  description Changed 11 years ago by Thijs Triemstra

Keywords: review added
Owner: Thijs Triemstra deleted
Status: assignednew

Replying to jml:

  • Don't recommend testing, refer to uqds
  • Don't use "I"
  • I certainly don't write code with a thesaurus open.
  • Twisted doesn't have any databases
  • "UNDOCUMENTED" as a docstring is never used

Addressed these points in r26445, putting it up for review.

comment:6 Changed 11 years ago by Glyph

Keywords: review removed
Owner: set to Thijs Triemstra
  1. TwistedDevelopment is probably more appropriate than the UQDS page.
  2. Why remove the thing about considering how you'd use the code?
  3. As long as we're updating the bit about docstrings, "whenever possible" should be replaced with something more forceful like "always" or just removed entirely.

Thanks for updating the coding standard :).

comment:7 in reply to:  6 Changed 11 years ago by Thijs Triemstra

Keywords: review added
Owner: changed from Thijs Triemstra to Glyph

Replying to glyph:

  1. TwistedDevelopment is probably more appropriate than the UQDS page.
  2. Why remove the thing about considering how you'd use the code?
  3. As long as we're updating the bit about docstrings, "whenever possible" should be replaced with something more forceful like "always" or just removed entirely.

Thanks for updating the coding standard :).

Fixed these points in r26474. I removed the thing about using the code because it had a reference to 'I' and I wasn't sure how to rewrite it properly. I added it back in and rewrote it, putting it up for review again.

comment:8 Changed 11 years ago by Glyph

Keywords: review removed
Owner: changed from Glyph to Thijs Triemstra

All right. That wording looks fine to me.

comment:9 in reply to:  8 Changed 11 years ago by Thijs Triemstra

Status: newassigned

Replying to glyph:

All right. That wording looks fine to me.

Cool, the doc builder is also happy: http://buildbot.twistedmatrix.com/builders/documentation/builds/348

comment:10 Changed 11 years ago by Thijs Triemstra

Resolution: fixed
Status: assignedclosed

(In [26476]) Merge crusty-standard-2217: Overall edit for the coding standard

Author: thijs Reviewer: glyph Fixes: #2217

comment:11 Changed 9 years ago by <automation>

Owner: Thijs Triemstra deleted
Note: See TracTickets for help on using tickets.