[Twisted-Python] TODO/FIXME/XXX comments

[Adi Roiban]

On 2 February 2015 at 06:55, Glyph <glyph at twistedmatrix.com> wrote:
>
> 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
>
> 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.

OK. I will try to work on this and we can discuss in the review.

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

I find it useful to have a few words describing why the fixme comment is there.
So I don't have to constantly hit the internet while I am reading twisted code.

I know that ticket description might change, but the comment should
state the reason why the fixme was created... an this should not
change.

The FIXME comment should be brief and it does not need to be the full
description.

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

I will try to do this.

Maybe, first we should move Specifications (as there is only one spec)

http://twistedmatrix.com/documents/current/core/specifications/banana.html

and Development of Twisted (as there are only small pages)

http://twistedmatrix.com/documents/current/core/development/index.html

This should make it much easier to update development documentation
and have development documentation in a single place.

What do you think?
I can take care of creating tickets  and submitting packages.

-- 
Adi Roiban