Opened 2 years ago

Last modified 16 months ago

#6012 enhancement new

Update coding standard docs about docstrings.

Reported by: jerub Owned by: jerub
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: Branch: branches/doc-docstrings-6012
(diff, github, buildbot, log)
Author: jerub Launchpad Bug:

Description

Docstrings should be gentle, docstrings should be kind. They should use triple-doublequotes, not triple-singlequotes, and emacs doesn't care about them so much anymore.

Fix up the docs to be clearer about these things

Change History (8)

comment:1 Changed 2 years ago by jerub

(In [35777]) Make branch for ticket: 'Update coding standard docs about docstrings'

Refs: #6012

comment:2 Changed 2 years ago by jerub

(In [35778]) Update the prose of coding-standard.xhtml to be clearer about docstrings.

Refs: #6012

comment:3 Changed 2 years ago by jerub

  • Author set to jerub
  • Branch set to branches/doc-docstrings-6012
  • Keywords review added
  • Status changed from new to assigned

comment:4 Changed 2 years ago by jerub

  • Owner jerub deleted
  • Status changed from assigned to new

comment:5 Changed 2 years ago by cyli

  • Keywords review removed
  • Owner set to jerub

The formatting makes it looks like the unordered list look like it has something to do with the previous paragraph ("Docstrings are never to be used to provide semantic information about an object; this rule may be violated if the code in question is to be used in a system where this is a requirement (such as Zope)."

http://twistedmatrix.com/trac/browser/branches/doc-docstrings-6012/doc/core/development/policy/coding-standard.xhtml?format=raw

Perhaps just an additional paragraph that says "Docstring formatting:" or something?

Also, maybe "opening triple-quotes and closing triple-quotes" instead of "opening" and "closing", since it's not very explicit what "opening" and "closing" refer to.

Other than that, looks good to merge!

comment:6 Changed 16 months ago by rwall

I noticed a typo in the branch "actual code can goes".

See also #6318 and #6301.

comment:7 Changed 16 months ago by rwall

Also mention that docstrings may occasionally be omitted if the method is already documented by a corresponding interface. eg #6459

comment:8 Changed 16 months ago by exarkun

Also mention that docstrings may occasionally be omitted if the method is already documented by a corresponding interface. eg #6459

Generally speaking this isn't really true. Or maybe I should say that "occasionally" really means "almost never" here. I agree that #6459 points out a valid problem, but it's very rare that there is *nothing* interesting to say about a particular implementation of an interface. So I'm not sure it's worth encouraging people to skip writing docstrings by pointing this out in the coding standard documentation.

Note: See TracTickets for help on using tickets.