Codetags - 用注释标记改进代码注释

Codetags是PEP 350的提案,常见的TODO就是Codetags的一种,用好Codetags可以让代码注释变得更可读、更易检索。

Codetags - 用注释标记改进代码注释

0 链接

PEP 350 -- Codetags

What Are Codetags?

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 FIXME, TODO, XXX, BUG, but there many more in wide use in existing software. Such markup will henceforth be referred to as codetags. These codetags may show up in application code, unit tests, scripts, general documentation, or wherever suitable.

1 Codetags

1.1 示例

Codetags是PEP 350种的一项编程提议,用在注释中。

例如:

1
2
3
4
5
6
7
8
9
class A:
def __init__(self):
# TODO: needs to be implemented
pass

def __add__(self, x):
# BUG: BUG here
return x

  • 注释中使用好Codetags,可以让代码更直观、更加易于检索。

另外,代码linting工具,如:pylint能够高亮显示出Codetags标记。

1.2 清单

PEP 350 -- Codetags

Mnemonics

TODO (MILESTONE, MLSTN, DONE, YAGNI, TBD, TOBEDONE)
To do: Informal tasks/features that are pending completion.
FIXME (XXX, DEBUG, BROKEN, REFACTOR, REFACT, RFCTR, OOPS, SMELL, NEEDSWORK, INSPECT)
Fix me: Areas of problematic or ugly code needing refactoring or cleanup.
BUG (BUGFIX)
Bugs: Reported defects tracked in bug database.
NOBUG (NOFIX, WONTFIX, DONTFIX, NEVERFIX, UNFIXABLE, CANTFIX)
Will Not Be Fixed: Problems that are well-known but will never be addressed due to design problems or domain limitations.
REQ (REQUIREMENT, STORY)
Requirements: Satisfactions of specific, formal requirements.
RFE (FEETCH, NYI, FR, FTRQ, FTR)
Requests For Enhancement: Roadmap items not yet implemented.
IDEA
Ideas: Possible RFE candidates, but less formal than RFE.
??? (QUESTION, QUEST, QSTN, WTF)
Questions: Misunderstood details.
!!! (ALERT)
Alerts: In need of immediate attention.
HACK (CLEVER, MAGIC)
Hacks: Temporary code to force inflexible functionality, or simply a test change, or workaround a known problem.
PORT (PORTABILITY, WKRD)
Portability: Workarounds specific to OS, Python version, etc.
CAVEAT (CAV, CAVT, WARNING, CAUTION)
Caveats: Implementation details/gotchas that stand out as non-intuitive.
NOTE (HELP)
Notes: Sections where a code reviewer found something that needs discussion or further investigation.
FAQ
Frequently Asked Questions: Interesting areas that require external explanation.
GLOSS (GLOSSARY)
Glossary: Definitions for project glossary.
SEE (REF, REFERENCE)
See: Pointers to other code, web link, etc.
TODOC (DOCDO, DODOC, NEEDSDOC, EXPLAIN, DOCUMENT)
Needs Documentation: Areas of code that still need to be documented.
CRED (CREDIT, THANKS)
Credits: Accreditations for external provision of enlightenment.
STAT (STATUS)
Status: File-level statistical indicator of maturity of this file.
RVD (REVIEWED, REVIEW)
Reviewed: File-level indicator that review was conducted.