657 lines
46 KiB
HTML
657 lines
46 KiB
HTML
|
||
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="color-scheme" content="light dark">
|
||
<title>PEP 350 – Codetags | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0350/">
|
||
<link rel="stylesheet" href="../_static/style.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/mq.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light">
|
||
<link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark">
|
||
<link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss">
|
||
<meta property="og:title" content='PEP 350 – Codetags | peps.python.org'>
|
||
<meta property="og:description" content="This informational PEP aims to provide guidelines for consistent use of codetags, which would enable the construction of standard utilities to take advantage of the codetag information, as well as making Python code more uniform across projects. Codeta...">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0350/">
|
||
<meta property="og:site_name" content="Python Enhancement Proposals (PEPs)">
|
||
<meta property="og:image" content="https://peps.python.org/_static/og-image.png">
|
||
<meta property="og:image:alt" content="Python PEPs">
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="description" content="This informational PEP aims to provide guidelines for consistent use of codetags, which would enable the construction of standard utilities to take advantage of the codetag information, as well as making Python code more uniform across projects. Codeta...">
|
||
<meta name="theme-color" content="#3776ab">
|
||
</head>
|
||
<body>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
|
||
<symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Following system colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="9"></circle>
|
||
<path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected dark colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
|
||
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected light colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="5"></circle>
|
||
<line x1="12" y1="1" x2="12" y2="3"></line>
|
||
<line x1="12" y1="21" x2="12" y2="23"></line>
|
||
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
|
||
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
|
||
<line x1="1" y1="12" x2="3" y2="12"></line>
|
||
<line x1="21" y1="12" x2="23" y2="12"></line>
|
||
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
|
||
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
|
||
</svg>
|
||
</symbol>
|
||
</svg>
|
||
<script>
|
||
|
||
document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto"
|
||
</script>
|
||
<section id="pep-page-section">
|
||
<header>
|
||
<h1>Python Enhancement Proposals</h1>
|
||
<ul class="breadcrumbs">
|
||
<li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li>
|
||
<li><a href="../pep-0000/">PEP Index</a> » </li>
|
||
<li>PEP 350</li>
|
||
</ul>
|
||
<button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())">
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg>
|
||
<span class="visually-hidden">Toggle light / dark / auto colour theme</span>
|
||
</button>
|
||
</header>
|
||
<article>
|
||
<section id="pep-content">
|
||
<h1 class="page-title">PEP 350 – Codetags</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Micah Elliott <mde at tracos.org></dd>
|
||
<dt class="field-even">Status<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Formally declined and will not be accepted">Rejected</abbr></dd>
|
||
<dt class="field-odd">Type<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><abbr title="Non-normative PEP containing background, guidelines or other information relevant to the Python ecosystem">Informational</abbr></dd>
|
||
<dt class="field-even">Created<span class="colon">:</span></dt>
|
||
<dd class="field-even">27-Jun-2005</dd>
|
||
<dt class="field-odd">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-odd">10-Aug-2005, 26-Sep-2005</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<section id="contents">
|
||
<details><summary>Table of Contents</summary><ul class="simple">
|
||
<li><a class="reference internal" href="#rejection-notice">Rejection Notice</a></li>
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#what-are-codetags">What Are Codetags?</a></li>
|
||
<li><a class="reference internal" href="#philosophy">Philosophy</a></li>
|
||
<li><a class="reference internal" href="#motivation">Motivation</a></li>
|
||
<li><a class="reference internal" href="#examples">Examples</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#general-syntax">General Syntax</a></li>
|
||
<li><a class="reference internal" href="#mnemonics">Mnemonics</a></li>
|
||
<li><a class="reference internal" href="#fields">Fields</a></li>
|
||
<li><a class="reference internal" href="#done-file">DONE File</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#tools">Tools</a></li>
|
||
<li><a class="reference internal" href="#objections">Objections</a></li>
|
||
<li><a class="reference internal" href="#references">References</a></li>
|
||
</ul>
|
||
</details></section>
|
||
<section id="rejection-notice">
|
||
<h2><a class="toc-backref" href="#rejection-notice" role="doc-backlink">Rejection Notice</a></h2>
|
||
<p>This PEP has been rejected. While the community may be interested,
|
||
there is no desire to make the standard library conform to this standard.</p>
|
||
</section>
|
||
<section id="abstract">
|
||
<h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2>
|
||
<p>This informational PEP aims to provide guidelines for consistent use
|
||
of <em>codetags</em>, which would enable the construction of standard
|
||
utilities to take advantage of the codetag information, as well as
|
||
making Python code more uniform across projects. Codetags also
|
||
represent a very lightweight programming micro-paradigm and become
|
||
useful for project management, documentation, change tracking, and
|
||
project health monitoring. This is submitted as a PEP because its
|
||
ideas are thought to be Pythonic, although the concepts are not unique
|
||
to Python programming. Herein are the definition of codetags, the
|
||
philosophy behind them, a motivation for standardized conventions,
|
||
some examples, a specification, a toolset description, and possible
|
||
objections to the Codetag project/paradigm.</p>
|
||
<p>This PEP is also living as a <a class="reference external" href="http://tracos.org/codetag/wiki/Pep">wiki</a> for people to add comments.</p>
|
||
</section>
|
||
<section id="what-are-codetags">
|
||
<h2><a class="toc-backref" href="#what-are-codetags" role="doc-backlink">What Are Codetags?</a></h2>
|
||
<p>Programmers widely use ad-hoc code comment markup conventions to serve
|
||
as reminders of sections of code that need closer inspection or
|
||
review. Examples of markup include <code class="docutils literal notranslate"><span class="pre">FIXME</span></code>, <code class="docutils literal notranslate"><span class="pre">TODO</span></code>, <code class="docutils literal notranslate"><span class="pre">XXX</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">BUG</span></code>, but there many more in wide use in existing software. Such
|
||
markup will henceforth be referred to as <em>codetags</em>. These codetags
|
||
may show up in application code, unit tests, scripts, general
|
||
documentation, or wherever suitable.</p>
|
||
<p>Codetags have been under discussion and in use (hundreds of codetags
|
||
in the Python 2.4 sources) in many places (e.g., <a class="reference external" href="http://c2.com/cgi/wiki?FixmeComment">c2</a>) for many years.
|
||
See <a class="reference internal" href="#references">References</a> for further historic and current information.</p>
|
||
</section>
|
||
<section id="philosophy">
|
||
<h2><a class="toc-backref" href="#philosophy" role="doc-backlink">Philosophy</a></h2>
|
||
<p>If you subscribe to most of these values, then codetags will likely be
|
||
useful for you.</p>
|
||
<ol class="arabic simple">
|
||
<li>As much information as possible should be contained <strong>inside the
|
||
source code</strong> (application code or unit tests). This along with
|
||
use of codetags impedes duplication. Most documentation can be
|
||
generated from that source code; e.g., by using help2man, man2html,
|
||
docutils, epydoc/pydoc, ctdoc, etc.</li>
|
||
<li>Information should be almost <strong>never duplicated</strong> – it should be
|
||
recorded in a single original format and all other locations should
|
||
be automatically generated from the original, or simply be
|
||
referenced. This is famously known as the Single Point Of
|
||
Truth (SPOT) or Don’t Repeat Yourself (DRY) rule.</li>
|
||
<li>Documentation that gets into customers’ hands should be
|
||
<strong>auto-generated</strong> from single sources into all other output
|
||
formats. People want documentation in many forms. It is thus
|
||
important to have a documentation system that can generate all of
|
||
these.</li>
|
||
<li>The <strong>developers are the documentation team</strong>. They write the code
|
||
and should know the code the best. There should not be a
|
||
dedicated, disjoint documentation team for any non-huge project.</li>
|
||
<li><strong>Plain text</strong> (with non-invasive markup) is the best format for
|
||
writing anything. All other formats are to be generated from the
|
||
plain text.</li>
|
||
</ol>
|
||
<p>Codetag design was influenced by the following goals:</p>
|
||
<ol class="upperalpha simple">
|
||
<li>Comments should be short whenever possible.</li>
|
||
<li>Codetag fields should be optional and of minimal length. Default
|
||
values and custom fields can be set by individual code shops.</li>
|
||
<li>Codetags should be minimalistic. The quicker it is to jot
|
||
something down, the more likely it is to get jotted.</li>
|
||
<li>The most common use of codetags will only have zero to two fields
|
||
specified, and these should be the easiest to type and read.</li>
|
||
</ol>
|
||
</section>
|
||
<section id="motivation">
|
||
<h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2>
|
||
<ul>
|
||
<li><strong>Various productivity tools can be built around codetags.</strong><p>See <a class="reference internal" href="#tools">Tools</a>.</p>
|
||
</li>
|
||
<li><strong>Encourages consistency.</strong><p>Historically, a subset of these codetags has been used informally in
|
||
the majority of source code in existence, whether in Python or in
|
||
other languages. Tags have been used in an inconsistent manner with
|
||
different spellings, semantics, format, and placement. For example,
|
||
some programmers might include datestamps and/or user identifiers,
|
||
limit to a single line or not, spell the codetag differently than
|
||
others, etc.</p>
|
||
</li>
|
||
<li><strong>Encourages adherence to SPOT/DRY principle.</strong><p>E.g., generating a roadmap dynamically from codetags instead of
|
||
keeping TODOs in sync with separate roadmap document.</p>
|
||
</li>
|
||
<li><strong>Easy to remember.</strong><p>All codetags must be concise, intuitive, and semantically
|
||
non-overlapping with others. The format must also be simple.</p>
|
||
</li>
|
||
<li><strong>Use not required/imposed.</strong><p>If you don’t use codetags already, there’s no obligation to start,
|
||
and no risk of affecting code (but see <a class="reference internal" href="#objections">Objections</a>). A small subset
|
||
can be adopted and the <a class="reference internal" href="#tools">Tools</a> will still be useful (a few codetags
|
||
have probably already been adopted on an ad-hoc basis anyway). Also
|
||
it is very easy to identify and remove (and possibly record) a
|
||
codetag that is no longer deemed useful.</p>
|
||
</li>
|
||
<li><strong>Gives a global view of code.</strong><p>Tools can be used to generate documentation and reports.</p>
|
||
</li>
|
||
<li><strong>A logical location for capturing CRCs/Stories/Requirements.</strong><p>The XP community often does not electronically capture Stories, but
|
||
codetags seem like a good place to locate them.</p>
|
||
</li>
|
||
<li><strong>Extremely lightweight process.</strong><p>Creating tickets in a tracking system for every thought degrades
|
||
development velocity. Even if a ticketing system is employed,
|
||
codetags are useful for simply containing links to those tickets.</p>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
<section id="examples">
|
||
<h2><a class="toc-backref" href="#examples" role="doc-backlink">Examples</a></h2>
|
||
<p>This shows a simple codetag as commonly found in sources everywhere
|
||
(with the addition of a trailing <code class="docutils literal notranslate"><span class="pre"><></span></code>):</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># FIXME: Seems like this loop should be finite. <></span>
|
||
<span class="k">while</span> <span class="kc">True</span><span class="p">:</span> <span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The following contrived example demonstrates a typical use of
|
||
codetags. It uses some of the available fields to specify the
|
||
assignees (a pair of programmers with initials <em>MDE</em> and <em>CLE</em>), the
|
||
Date of expected completion (<em>Week 14</em>), and the Priority of the item
|
||
(<em>2</em>):</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># FIXME: Seems like this loop should be finite. <MDE,CLE d:14w p:2></span>
|
||
<span class="k">while</span> <span class="kc">True</span><span class="p">:</span> <span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This codetag shows a bug with fields describing author, discovery
|
||
(origination) date, due date, and priority:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># BUG: Crashes if run on Sundays.</span>
|
||
<span class="c1"># <MDE 2005-09-04 d:14w p:2></span>
|
||
<span class="k">if</span> <span class="n">day</span> <span class="o">==</span> <span class="s1">'Sunday'</span><span class="p">:</span> <span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Here is a demonstration of how not to use codetags. This has many
|
||
problems: 1) Codetags cannot share a line with code; 2) Missing colon
|
||
after mnemonic; 3) A codetag referring to codetags is usually useless,
|
||
and worse, it is not completable; 4) No need to have a bunch of fields
|
||
for a trivial codetag; 5) Fields with unknown values (<code class="docutils literal notranslate"><span class="pre">t:XXX</span></code>)
|
||
should not be used:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">i</span> <span class="o">=</span> <span class="n">i</span> <span class="o">+</span> <span class="mi">1</span> <span class="c1"># TODO Add some more codetags.</span>
|
||
<span class="c1"># <JRNewbie 2005-04-03 d:2005-09-03 t:XXX d:14w p:0 s:inprogress></span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="specification">
|
||
<h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2>
|
||
<p>This describes the format: syntax, mnemonic names, fields, and
|
||
semantics, and also the separate DONE File.</p>
|
||
<section id="general-syntax">
|
||
<h3><a class="toc-backref" href="#general-syntax" role="doc-backlink">General Syntax</a></h3>
|
||
<p>Each codetag should be inside a comment, and can be any number of
|
||
lines. It should not share a line with code. It should match the
|
||
indentation of surrounding code. The end of the codetag is marked by
|
||
a pair of angle brackets <code class="docutils literal notranslate"><span class="pre"><></span></code> containing optional fields, which must
|
||
not be split onto multiple lines. It is preferred to have a codetag
|
||
in <code class="docutils literal notranslate"><span class="pre">#</span></code> comments instead of string comments. There can be multiple
|
||
fields per codetag, all of which are optional.</p>
|
||
<p>In short, a codetag consists of a mnemonic, a colon, commentary text,
|
||
an opening angle bracket, an optional list of fields, and a closing
|
||
angle bracket. E.g.,</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># MNEMONIC: Some (maybe multi-line) commentary. <field field ...></span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="mnemonics">
|
||
<h3><a class="toc-backref" href="#mnemonics" role="doc-backlink">Mnemonics</a></h3>
|
||
<p>The codetags of interest are listed below, using the following format:</p>
|
||
<div class="line-block">
|
||
<div class="line"><code class="docutils literal notranslate"><span class="pre">recommended</span> <span class="pre">mnemonic</span> <span class="pre">(&</span> <span class="pre">synonym</span> <span class="pre">list)</span></code></div>
|
||
<div class="line-block">
|
||
<div class="line"><em>canonical name</em>: semantics</div>
|
||
</div>
|
||
</div>
|
||
<dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">TODO</span> <span class="pre">(MILESTONE,</span> <span class="pre">MLSTN,</span> <span class="pre">DONE,</span> <span class="pre">YAGNI,</span> <span class="pre">TBD,</span> <span class="pre">TOBEDONE)</span></code></dt><dd><em>To do</em>: Informal tasks/features that are pending completion.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">FIXME</span> <span class="pre">(XXX,</span> <span class="pre">DEBUG,</span> <span class="pre">BROKEN,</span> <span class="pre">REFACTOR,</span> <span class="pre">REFACT,</span> <span class="pre">RFCTR,</span> <span class="pre">OOPS,</span> <span class="pre">SMELL,</span> <span class="pre">NEEDSWORK,</span> <span class="pre">INSPECT)</span></code></dt><dd><em>Fix me</em>: Areas of problematic or ugly code needing refactoring or
|
||
cleanup.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">BUG</span> <span class="pre">(BUGFIX)</span></code></dt><dd><em>Bugs</em>: Reported defects tracked in bug database.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">NOBUG</span> <span class="pre">(NOFIX,</span> <span class="pre">WONTFIX,</span> <span class="pre">DONTFIX,</span> <span class="pre">NEVERFIX,</span> <span class="pre">UNFIXABLE,</span> <span class="pre">CANTFIX)</span></code></dt><dd><em>Will Not Be Fixed</em>: Problems that are well-known but will never be
|
||
addressed due to design problems or domain limitations.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">REQ</span> <span class="pre">(REQUIREMENT,</span> <span class="pre">STORY)</span></code></dt><dd><em>Requirements</em>: Satisfactions of specific, formal requirements.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">RFE</span> <span class="pre">(FEETCH,</span> <span class="pre">NYI,</span> <span class="pre">FR,</span> <span class="pre">FTRQ,</span> <span class="pre">FTR)</span></code></dt><dd><em>Requests For Enhancement</em>: Roadmap items not yet implemented.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">IDEA</span></code></dt><dd><em>Ideas</em>: Possible RFE candidates, but less formal than RFE.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">???</span> <span class="pre">(QUESTION,</span> <span class="pre">QUEST,</span> <span class="pre">QSTN,</span> <span class="pre">WTF)</span></code></dt><dd><em>Questions</em>: Misunderstood details.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">!!!</span> <span class="pre">(ALERT)</span></code></dt><dd><em>Alerts</em>: In need of immediate attention.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">HACK</span> <span class="pre">(CLEVER,</span> <span class="pre">MAGIC)</span></code></dt><dd><em>Hacks</em>: Temporary code to force inflexible functionality, or
|
||
simply a test change, or workaround a known problem.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">PORT</span> <span class="pre">(PORTABILITY,</span> <span class="pre">WKRD)</span></code></dt><dd><em>Portability</em>: Workarounds specific to OS, Python version, etc.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">CAVEAT</span> <span class="pre">(CAV,</span> <span class="pre">CAVT,</span> <span class="pre">WARNING,</span> <span class="pre">CAUTION)</span></code></dt><dd><em>Caveats</em>: Implementation details/gotchas that stand out as
|
||
non-intuitive.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">NOTE</span> <span class="pre">(HELP)</span></code></dt><dd><em>Notes</em>: Sections where a code reviewer found something that needs
|
||
discussion or further investigation.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">FAQ</span></code></dt><dd><em>Frequently Asked Questions</em>: Interesting areas that require
|
||
external explanation.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">GLOSS</span> <span class="pre">(GLOSSARY)</span></code></dt><dd><em>Glossary</em>: Definitions for project glossary.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">SEE</span> <span class="pre">(REF,</span> <span class="pre">REFERENCE)</span></code></dt><dd><em>See</em>: Pointers to other code, web link, etc.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">TODOC</span> <span class="pre">(DOCDO,</span> <span class="pre">DODOC,</span> <span class="pre">NEEDSDOC,</span> <span class="pre">EXPLAIN,</span> <span class="pre">DOCUMENT)</span></code></dt><dd><em>Needs Documentation</em>: Areas of code that still need to be
|
||
documented.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">CRED</span> <span class="pre">(CREDIT,</span> <span class="pre">THANKS)</span></code></dt><dd><em>Credits</em>: Accreditations for external provision of enlightenment.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">STAT</span> <span class="pre">(STATUS)</span></code></dt><dd><em>Status</em>: File-level statistical indicator of maturity of this
|
||
file.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">RVD</span> <span class="pre">(REVIEWED,</span> <span class="pre">REVIEW)</span></code></dt><dd><em>Reviewed</em>: File-level indicator that review was conducted.</dd>
|
||
</dl>
|
||
<p>File-level codetags might be better suited as properties in the
|
||
revision control system, but might still be appropriately specified in
|
||
a codetag.</p>
|
||
<p>Some of these are temporary (e.g., <code class="docutils literal notranslate"><span class="pre">FIXME</span></code>) while others are
|
||
persistent (e.g., <code class="docutils literal notranslate"><span class="pre">REQ</span></code>). A mnemonic was chosen over a synonym
|
||
using three criteria: descriptiveness, length (shorter is better),
|
||
commonly used.</p>
|
||
<p>Choosing between <code class="docutils literal notranslate"><span class="pre">FIXME</span></code> and <code class="docutils literal notranslate"><span class="pre">XXX</span></code> is difficult. <code class="docutils literal notranslate"><span class="pre">XXX</span></code> seems to
|
||
be more common, but much less descriptive. Furthermore, <code class="docutils literal notranslate"><span class="pre">XXX</span></code> is a
|
||
useful placeholder in a piece of code having a value that is unknown.
|
||
Thus <code class="docutils literal notranslate"><span class="pre">FIXME</span></code> is the preferred spelling. <a class="reference external" href="http://java.sun.com/docs/codeconv/html/CodeConventions.doc9.html#395">Sun says</a> that <code class="docutils literal notranslate"><span class="pre">XXX</span></code>
|
||
and <code class="docutils literal notranslate"><span class="pre">FIXME</span></code> are slightly different, giving <code class="docutils literal notranslate"><span class="pre">XXX</span></code> higher severity.
|
||
However, with decades of chaos on this topic, and too many millions of
|
||
developers who won’t be influenced by Sun, it is easy to rightly call
|
||
them synonyms.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">DONE</span></code> is always a completed <code class="docutils literal notranslate"><span class="pre">TODO</span></code> item, but this should probably
|
||
be indicated through the revision control system and/or a completion
|
||
recording mechanism (see <a class="reference internal" href="#done-file">DONE File</a>).</p>
|
||
<p>It may be a useful metric to count <code class="docutils literal notranslate"><span class="pre">NOTE</span></code> tags: a high count may
|
||
indicate a design (or other) problem. But of course the majority of
|
||
codetags indicate areas of code needing some attention.</p>
|
||
<p>An <code class="docutils literal notranslate"><span class="pre">FAQ</span></code> is probably more appropriately documented in a wiki where
|
||
users can more easily view and contribute.</p>
|
||
</section>
|
||
<section id="fields">
|
||
<h3><a class="toc-backref" href="#fields" role="doc-backlink">Fields</a></h3>
|
||
<p>All fields are optional. The proposed standard fields are described
|
||
in this section. Note that upper case field characters are intended
|
||
to be replaced.</p>
|
||
<p>The <em>Originator/Assignee</em> and <em>Origination Date/Week</em> fields are the
|
||
most common and don’t usually require a prefix.</p>
|
||
<p>This lengthy list of fields is liable to scare people (the intended
|
||
minimalists) away from adopting codetags, but keep in mind that these
|
||
only exist to support programmers who either 1) like to keep <code class="docutils literal notranslate"><span class="pre">BUG</span></code>
|
||
or <code class="docutils literal notranslate"><span class="pre">RFE</span></code> codetags in a complete form, or 2) are using codetags as
|
||
their complete and only tracking system. In other words, many of
|
||
these fields will be used very rarely. They are gathered largely from
|
||
industry-wide conventions, and example sources include <a class="reference external" href="http://gcc.gnu.org/bugzilla/">GCC
|
||
Bugzilla</a> and <a class="reference external" href="http://sourceforge.net/tracker/?group_id=5470">Python’s SourceForge</a> tracking systems.</p>
|
||
<dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">AAA[,BBB]...</span></code></dt><dd>List of <em>Originator</em> or <em>Assignee</em> initials (the context
|
||
determines which unless both should exist). It is also okay to
|
||
use usernames such as <code class="docutils literal notranslate"><span class="pre">MicahE</span></code> instead of initials. Initials
|
||
(in upper case) are the preferred form.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">a:AAA[,BBB]...</span></code></dt><dd>List of <em>Assignee</em> initials. This is necessary only in (rare)
|
||
cases where a codetag has both an assignee and an originator, and
|
||
they are different. Otherwise the <code class="docutils literal notranslate"><span class="pre">a:</span></code> prefix is omitted, and
|
||
context determines the intent. E.g., <code class="docutils literal notranslate"><span class="pre">FIXME</span></code> usually has an
|
||
<em>Assignee</em>, and <code class="docutils literal notranslate"><span class="pre">NOTE</span></code> usually has an <em>Originator</em>, but if a
|
||
<code class="docutils literal notranslate"><span class="pre">FIXME</span></code> was originated (and initialed) by a reviewer, then the
|
||
assignee’s initials would need a <code class="docutils literal notranslate"><span class="pre">a:</span></code> prefix.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">YYYY[-MM[-DD]]</span></code> or <code class="docutils literal notranslate"><span class="pre">WW[.D]w</span></code></dt><dd>The <em>Origination Date</em> indicating when the comment was added, in
|
||
<a class="reference external" href="http://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format (digits and hyphens only). Or <em>Origination
|
||
Week</em>, an alternative form for specifying an <em>Origination Date</em>.
|
||
A day of the week can be optionally specified. The <code class="docutils literal notranslate"><span class="pre">w</span></code> suffix
|
||
is necessary for distinguishing from a date.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">d:YYYY[-MM[-DD]]</span></code> or <code class="docutils literal notranslate"><span class="pre">d:WW[.D]w</span></code></dt><dd><em>Due Date (d)</em> target completion (estimate). Or <em>Due Week (d)</em>,
|
||
an alternative to specifying a <em>Due Date</em>.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">p:N</span></code></dt><dd><em>Priority (p)</em> level. Range (N) is from 0..3 with 3 being the
|
||
highest. 0..3 are analogous to low, medium, high, and
|
||
showstopper/critical. The <em>Severity</em> field could be factored into
|
||
this single number, and doing so is recommended since having both
|
||
is subject to varying interpretation. The range and order should
|
||
be customizable. The existence of this field is important for any
|
||
tool that itemizes codetags. Thus a (customizable) default value
|
||
should be supported.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">t:NNNN</span></code></dt><dd><em>Tracker (t)</em> number corresponding to associated Ticket ID in
|
||
separate tracking system.</dd>
|
||
</dl>
|
||
<p>The following fields are also available but expected to be less
|
||
common.</p>
|
||
<dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">c:AAAA</span></code></dt><dd><em>Category (c)</em> indicating some specific area affected by this
|
||
item.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">s:AAAA</span></code></dt><dd><em>Status (s)</em> indicating state of item. Examples are “unexplored”,
|
||
“understood”, “inprogress”, “fixed”, “done”, “closed”. Note that
|
||
when an item is completed it is probably better to remove the
|
||
codetag and record it in a <a class="reference internal" href="#done-file">DONE File</a>.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">i:N</span></code></dt><dd>Development cycle <em>Iteration (i)</em>. Useful for grouping codetags into
|
||
completion target groups.</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">r:N</span></code></dt><dd>Development cycle <em>Release (r)</em>. Useful for grouping codetags into
|
||
completion target groups.</dd>
|
||
</dl>
|
||
<p>To summarize, the non-prefixed fields are initials and origination
|
||
date, and the prefixed fields are: assignee (a), due (d), priority
|
||
(p), tracker (t), category (c), status (s), iteration (i), and release
|
||
(r).</p>
|
||
<p>It should be possible for groups to define or add their own fields,
|
||
and these should have upper case prefixes to distinguish them from the
|
||
standard set. Examples of custom fields are <em>Operating System (O)</em>,
|
||
<em>Severity (S)</em>, <em>Affected Version (A)</em>, <em>Customer (C)</em>, etc.</p>
|
||
</section>
|
||
<section id="done-file">
|
||
<h3><a class="toc-backref" href="#done-file" role="doc-backlink">DONE File</a></h3>
|
||
<p>Some codetags have an ability to be <em>completed</em> (e.g., <code class="docutils literal notranslate"><span class="pre">FIXME</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">TODO</span></code>, <code class="docutils literal notranslate"><span class="pre">BUG</span></code>). It is often important to retain completed items
|
||
by recording them with a completion date stamp. Such completed items
|
||
are best stored in a single location, global to a project (or maybe a
|
||
package). The proposed format is most easily described by an example,
|
||
say <code class="docutils literal notranslate"><span class="pre">~/src/fooproj/DONE</span></code>:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># TODO: Recurse into subdirs only on blue</span>
|
||
<span class="c1"># moons. <MDE 2003-09-26></span>
|
||
<span class="p">[</span><span class="mi">2005</span><span class="o">-</span><span class="mi">09</span><span class="o">-</span><span class="mi">26</span> <span class="n">Oops</span><span class="p">,</span> <span class="n">I</span> <span class="n">underestimated</span> <span class="n">this</span> <span class="n">one</span> <span class="n">a</span> <span class="n">bit</span><span class="o">.</span> <span class="n">Should</span> <span class="n">have</span>
|
||
<span class="n">used</span> <span class="n">Warsaw</span><span class="s1">'s First Law!]</span>
|
||
|
||
<span class="c1"># FIXME: ...</span>
|
||
<span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>You can see that the codetag is copied verbatim from the original
|
||
source file. The date stamp is then entered on the following line
|
||
with an optional post-mortem commentary. The entry is terminated by a
|
||
blank line (<code class="docutils literal notranslate"><span class="pre">\n\n</span></code>).</p>
|
||
<p>It may sound burdensome to have to delete codetag lines every time one
|
||
gets completed. But in practice it is quite easy to setup a Vim or
|
||
Emacs mapping to auto-record a codetag deletion in this format (sans
|
||
the commentary).</p>
|
||
</section>
|
||
</section>
|
||
<section id="tools">
|
||
<h2><a class="toc-backref" href="#tools" role="doc-backlink">Tools</a></h2>
|
||
<p>Currently, programmers (and sometimes analysts) typically use <em>grep</em>
|
||
to generate a list of items corresponding to a single codetag.
|
||
However, various hypothetical productivity tools could take advantage
|
||
of a consistent codetag format. Some example tools follow.</p>
|
||
<dl class="simple">
|
||
<dt>Document Generator</dt><dd>Possible docs: glossary, roadmap, manpages</dd>
|
||
<dt>Codetag History</dt><dd>Track (with revision control system interface) when a <code class="docutils literal notranslate"><span class="pre">BUG</span></code> tag
|
||
(or any codetag) originated/resolved in a code section</dd>
|
||
<dt>Code Statistics</dt><dd>A project Health-O-Meter</dd>
|
||
<dt>Codetag Lint</dt><dd>Notify of invalid use of codetags, and aid in porting to codetags</dd>
|
||
<dt>Story Manager/Browser</dt><dd>An electronic means to replace XP notecards. In MVC terms, the
|
||
codetag is the Model, and the Story Manager could be a graphical
|
||
Viewer/Controller to do visual rearrangement, prioritization, and
|
||
assignment, milestone management.</dd>
|
||
<dt>Any Text Editor</dt><dd>Used for changing, removing, adding, rearranging, recording
|
||
codetags.</dd>
|
||
</dl>
|
||
<p>There are some tools already in existence that take advantage of a
|
||
smaller set of pseudo-codetags (see <a class="reference internal" href="#references">References</a>). There is also an
|
||
example codetags implementation under way, known as the <a class="reference external" href="http://tracos.org/codetag">Codetag
|
||
Project</a>.</p>
|
||
</section>
|
||
<section id="objections">
|
||
<h2><a class="toc-backref" href="#objections" role="doc-backlink">Objections</a></h2>
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">Objection<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Extreme Programming argues that such codetags should not
|
||
ever exist in code since the code is the documentation.</dd>
|
||
<dt class="field-even">Defense<span class="colon">:</span></dt>
|
||
<dd class="field-even">Maybe you should put the codetags in the unit test files
|
||
instead. Besides, it’s tough to generate documentation from
|
||
uncommented source code.</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">Objection<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Too much existing code has not followed proposed
|
||
guidelines.</dd>
|
||
<dt class="field-even">Defense<span class="colon">:</span></dt>
|
||
<dd class="field-even">[Simple] utilities (<em>ctlint</em>) could convert existing codes.</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">Objection<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Causes duplication with tracking system.</dd>
|
||
<dt class="field-even">Defense<span class="colon">:</span></dt>
|
||
<dd class="field-even">Not really, unless fields are abused. If an item exists in
|
||
the tracker, a simple ticket number in the codetag tracker field
|
||
is sufficient. Maybe a duplicated title would be acceptable.
|
||
Furthermore, it’s too burdensome to have a ticket filed for every
|
||
item that pops into a developer’s mind on-the-go. Additionally,
|
||
the tracking system could possibly be obviated for simple or small
|
||
projects that can reasonably fit the relevant data into a codetag.</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">Objection<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Codetags are ugly and clutter code.</dd>
|
||
<dt class="field-even">Defense<span class="colon">:</span></dt>
|
||
<dd class="field-even">That is a good point. But I’d still rather have such info
|
||
in a single place (the source code) than various other documents,
|
||
likely getting duplicated or forgotten about. The completed
|
||
codetags can be sent off to the <a class="reference internal" href="#done-file">DONE File</a>, or to the bit
|
||
bucket.</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">Objection<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Codetags (and all comments) get out of date.</dd>
|
||
<dt class="field-even">Defense<span class="colon">:</span></dt>
|
||
<dd class="field-even">Not so much if other sources (externally visible
|
||
documentation) depend on their being accurate.</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">Objection<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Codetags tend to only rarely have estimated completion
|
||
dates of any sort. OK, the fields are optional, but you want to
|
||
suggest fields that actually will be widely used.</dd>
|
||
<dt class="field-even">Defense<span class="colon">:</span></dt>
|
||
<dd class="field-even">If an item is inestimable don’t bother with specifying a
|
||
date field. Using tools to display items with order and/or color
|
||
by due date and/or priority, it is easier to make estimates.
|
||
Having your roadmap be a dynamic reflection of your codetags makes
|
||
you much more likely to keep the codetags accurate.</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">Objection<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Named variables for the field parameters in the <code class="docutils literal notranslate"><span class="pre"><></span></code>
|
||
should be used instead of cryptic one-character prefixes. I.e.,
|
||
<MDE p:3> should rather be <author=MDE, priority=3>.</dd>
|
||
<dt class="field-even">Defense<span class="colon">:</span></dt>
|
||
<dd class="field-even">It is just too much typing/verbosity to spell out fields. I
|
||
argue that <code class="docutils literal notranslate"><span class="pre">p:3</span> <span class="pre">i:2</span></code> is as readable as <code class="docutils literal notranslate"><span class="pre">priority=3,</span>
|
||
<span class="pre">iteration=2</span></code> and is much more likely to by typed and remembered
|
||
(see bullet C in <a class="reference internal" href="#philosophy">Philosophy</a>). In this case practicality beats
|
||
purity. There are not many fields to keep track of so one letter
|
||
prefixes are suitable.</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">Objection<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Synonyms should be deprecated since it is better to have a
|
||
single way to spell something.</dd>
|
||
<dt class="field-even">Defense<span class="colon">:</span></dt>
|
||
<dd class="field-even">Many programmers prefer short mnemonic names, especially in
|
||
comments. This is why short mnemonics were chosen as the primary
|
||
names. However, others feel that an explicit spelling is less
|
||
confusing and less prone to error. There will always be two camps
|
||
on this subject. Thus synonyms (and complete, full spellings)
|
||
should remain supported.</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">Objection<span class="colon">:</span></dt>
|
||
<dd class="field-odd">It is cruel to use [for mnemonics] opaque acronyms and
|
||
abbreviations which drop vowels; it’s hard to figure these things
|
||
out. On that basis I hate: MLSTN RFCTR RFE FEETCH, NYI, FR, FTRQ,
|
||
FTR WKRD RVDBY</dd>
|
||
<dt class="field-even">Defense<span class="colon">:</span></dt>
|
||
<dd class="field-even">Mnemonics are preferred since they are pretty easy to
|
||
remember and take up less space. If programmers didn’t like
|
||
dropping vowels we would be able to fit very little code on a
|
||
line. The space is important for those who write comments that
|
||
often fit on a single line. But when using a canon everywhere it
|
||
is much less likely to get something to fit on a line.</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">Objection<span class="colon">:</span></dt>
|
||
<dd class="field-odd">It takes too long to type the fields.</dd>
|
||
<dt class="field-even">Defense<span class="colon">:</span></dt>
|
||
<dd class="field-even">Then don’t use (most or any of) them, especially if you’re
|
||
the only programmer. Terminating a codetag with <code class="docutils literal notranslate"><span class="pre"><></span></code> is a small
|
||
chore, and in doing so you enable the use of the proposed tools.
|
||
Editor auto-completion of codetags is also useful: You can
|
||
program your editor to stamp a template (e.g. <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">FIXME</span> <span class="pre">.</span> <span class="pre"><MDE</span>
|
||
<span class="pre">{date}></span></code>) with just a keystroke or two.</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">Objection<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><em>WorkWeek</em> is an obscure and uncommon time unit.</dd>
|
||
<dt class="field-even">Defense<span class="colon">:</span></dt>
|
||
<dd class="field-even">That’s true but it is a highly suitable unit of granularity
|
||
for estimation/targeting purposes, and it is very compact. The
|
||
<a class="reference external" href="http://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> is widely understood but allows you to only specify
|
||
either a specific day (restrictive) or month (broad).</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">Objection<span class="colon">:</span></dt>
|
||
<dd class="field-odd">I aesthetically dislike for the comment to be terminated
|
||
with <> in the empty field case.</dd>
|
||
<dt class="field-even">Defense<span class="colon">:</span></dt>
|
||
<dd class="field-even">It is necessary to have a terminator since codetags may be
|
||
followed by non-codetag comments. Or codetags could be limited to
|
||
a single line, but that’s prohibitive. I can’t think of any
|
||
single-character terminator that is appropriate and significantly
|
||
better than <>. Maybe <code class="docutils literal notranslate"><span class="pre">@</span></code> could be a terminator, but then most
|
||
codetags will have an unnecessary @.</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">Objection<span class="colon">:</span></dt>
|
||
<dd class="field-odd">I can’t use codetags when writing HTML, or less
|
||
specifically, XML. Maybe <code class="docutils literal notranslate"><span class="pre">@fields@</span></code> would be a better than
|
||
<code class="docutils literal notranslate"><span class="pre"><fields></span></code> as the delimiters.</dd>
|
||
<dt class="field-even">Defense<span class="colon">:</span></dt>
|
||
<dd class="field-even">Maybe you’re right, but <code class="docutils literal notranslate"><span class="pre"><></span></code> looks nicer whenever
|
||
applicable. XML/SGML could use <code class="docutils literal notranslate"><span class="pre">@</span></code> while more common
|
||
programming languages stick to <code class="docutils literal notranslate"><span class="pre"><></span></code>.</dd>
|
||
</dl>
|
||
</section>
|
||
<section id="references">
|
||
<h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2>
|
||
<p>Some other tools have approached defining/exploiting codetags.
|
||
See <a class="reference external" href="http://tracos.org/codetag/wiki/Links">http://tracos.org/codetag/wiki/Links</a>.</p>
|
||
</section>
|
||
</section>
|
||
<hr class="docutils" />
|
||
<p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0350.rst">https://github.com/python/peps/blob/main/peps/pep-0350.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0350.rst">2023-09-09 17:39:29 GMT</a></p>
|
||
|
||
</article>
|
||
<nav id="pep-sidebar">
|
||
<h2>Contents</h2>
|
||
<ul>
|
||
<li><a class="reference internal" href="#rejection-notice">Rejection Notice</a></li>
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#what-are-codetags">What Are Codetags?</a></li>
|
||
<li><a class="reference internal" href="#philosophy">Philosophy</a></li>
|
||
<li><a class="reference internal" href="#motivation">Motivation</a></li>
|
||
<li><a class="reference internal" href="#examples">Examples</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#general-syntax">General Syntax</a></li>
|
||
<li><a class="reference internal" href="#mnemonics">Mnemonics</a></li>
|
||
<li><a class="reference internal" href="#fields">Fields</a></li>
|
||
<li><a class="reference internal" href="#done-file">DONE File</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#tools">Tools</a></li>
|
||
<li><a class="reference internal" href="#objections">Objections</a></li>
|
||
<li><a class="reference internal" href="#references">References</a></li>
|
||
</ul>
|
||
|
||
<br>
|
||
<a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0350.rst">Page Source (GitHub)</a>
|
||
</nav>
|
||
</section>
|
||
<script src="../_static/colour_scheme.js"></script>
|
||
<script src="../_static/wrap_tables.js"></script>
|
||
<script src="../_static/sticky_banner.js"></script>
|
||
</body>
|
||
</html> |