Diff for "PolicyandProcess/XXXPolicy"

Not logged in - Log In / Register

Differences between revisions 1 and 5 (spanning 4 versions)
Revision 1 as of 2009-09-10 22:35:16
Size: 1888
Editor: jml
Comment:
Revision 5 as of 2012-05-31 16:33:21
Size: 2102
Editor: jml
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
## page was renamed from XXXPolicy
Line 11: Line 12:
# XXX: SteveAlexander 2007-03-12 bug=12345: This code is going to
# fail aft
er next year.}}}
# XXX: SteveAlexander YYYY-MM-DD bug=NNNN: Comment here.}}}
Line 16: Line 16:
  * We should ensure that there is a bug or spec assigned to each XXX.   * Consider filing a bug or spec for an XXX. 
Line 26: Line 26:

== Principles ==

 * Each XXX is an indicator of tech debt (not the debt itself)
 * We must strive to eliminate tech debt
 * Marking existing code that ought to be cleaned with an XXX is good
 * Actually cleaning up code is best

  • Policy Name: XXX Policy (aka The Triple X Policy)

  • Policy Owner: Joey Stanford

Policy Statement

  1. We put "XXX" in our code in a specific format to denote areas requiring follow up.
    • Python

      # XXX: SteveAlexander YYYY-MM-DD bug=NNNN: Comment here.
    • TAL

      <tal:XXX condition="nothing">YYYYMMDD mpt: Comment here.</tal:XXX>
      • The XXX cannot be followed by a colon here, because that would be an XML error. And if the XXX was put inside the element instead, that would make the code longer and XXXes a bit harder to find. (See also bug 120005, "Page template comment syntax is too verbose".)

    • Consider filing a bug or spec for an XXX.
    • Our current tools use the following regex (XXX:?|TODO|FIXME) which means XXX will be found even if it does not have a colon.

    • TODO comments are permitted in the same format. See Zope's comments on this.

    • FIXME items should be listed as XXX.
  2. Reviewers will not approve code that does not follow this format.
  3. Developers when modifying code which contains an XXX block should strive to resolve the XXX if possible.

Rationale

  • The use of this standardized format allows us to write scripts which scan our code for these areas and generate reports. This enables us to identify areas of our code which may need further attention.

Principles

  • Each XXX is an indicator of tech debt (not the debt itself)
  • We must strive to eliminate tech debt
  • Marking existing code that ought to be cleaned with an XXX is good
  • Actually cleaning up code is best

Scope

  • Affects: All Launchpad Code
  • Term: Permanent

Supporting Documentation

Comments

PolicyandProcess/XXXPolicy (last edited 2012-05-31 16:33:21 by jml)