[bind10-dev] XXX, TODO, and suchlike

[Shane Kerr]

All,

I was looking through my tickets, and came across an old one:

http://bind10.isc.org/ticket/101

It's one year old today! Happy birthday ticket #101!

Anyway, Jinmei's comment reads:

        We often leave comments including "XXX", "TODO", etc, to
        indicate the relevant code fragment has a potential problem or
        needs to be revisited by the release time, etc.

        Right now, different developers use different keywords, but it's
        better to have a consistent style project-wide.

I seem to recall that we have discussed this before. 

Anyway, we have a lot more 'TODO' comments than 'XXX' in the code.

In my mind they are slightly different.

'TODO' comments may refer to things which may be left off indefinitely,
but are helpful reminders for anyone looking through the code. For
example, inefficient algorithms or missing corner cases can be
documented.

'XXX' tend to be things which are actually bad, but for whatever reason
the developer decided to leave them in. So, for example:

        # finally, send SIGKILL (unmaskable termination) until everybody dies
        while self.processes:
            # XXX: some delay probably useful... how much is uncertain
            time.sleep(0.1)
            self.reap_children()

It's an alert to anyone reading the code that this value is completely
arbitrary, and quite possibly bogus.

The distinction is subtle - often TODO and XXX basically mean the same
thing. 

Anyway, that's my take on it. I'd like to close the ticket, so please
discuss. :)

--
Shane