[Twisted-Python] TODO/FIXME/XXX comments

Glyph glyph at twistedmatrix.com
Sun Feb 1 23:55:44 MST 2015


> On Feb 1, 2015, at 6:16 AM, Adi Roiban <adi at roiban.ro> wrote:
> 
> Hi,
> 
> The coding standard contains:
> 
> "Comments marked with XXX or TODO must contain a reference to the
> associated ticket."
> 
> -----
> 
> Are there more hints about how to write XXX/TODO comments or how not
> to write them?
> 
> Instead of
> 
> XXX: If the client makes arbitrary CTCP queries,
> this method should probably show the responses to
> them instead of treating them as anomalies.
> 
> is this new comment better?
> 
> FIXME:7560:
> Add code for handling arbitrary queries and not treat them as
> anomalies.

Yes, this is much better, but better still would be simply:

# FIXME: https://twistedmatrix.com/trac/ticket/7560 <https://twistedmatrix.com/trac/ticket/7560>

The actual guidance should probably be changed to say to include an actual hyperlink to the ticket, so that if we migrate to a new bug tracker (an imminent possibility with so much interest in switching to Git and then Github) we can keep all the references current by setting up URL redirects.

Also, there's rarely a point to putting a copy of the bug's description in the code; that should be kept up to date in the bug tracker and not duplicated.

> ------
> 
> Maybe  we can update the styleguide with an example of a bad TODO
> comment and a god TODO comment.

That would be great.

> For my project I use a specific marker for TODO comments so that it
> much easier to automate some checks.. (ex no comments for closed
> tickets are left in the code) or provide a list with
> TODO/tech-debt tickets.
> 
> 
> What do you think?
> -- 
> Adi Roiban
> 
> _______________________________________________
> Twisted-Python mailing list
> Twisted-Python at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20150201/2a766730/attachment-0002.html>


More information about the Twisted-Python mailing list