Ok, let me summarise this:

• a @[asf.]todo tag marginally improves the formatting of a javadoc
• nobody really likes the idea of using a namespaced version of todo
• it is possible to tweak Checkstyle and the javadoc command to enable
  the use of @todo

That said:
• todo statements generally have little to do (sic) in a javadoc comment
• TODO keywords are easily indexable by modern IDEs

Jeremias recommends the Felix way: using //TODO comments below the
javadoc. I’m also strongly in favour of this convention. OTOH, if I’m
correct nobody strongly feels that @todo tags are necessary.

So I think we have a consensus:
• from now on we stop using @todo in favour of the Felix convention;
• we will progressively remove TODO statements from javadoc comments and
  move them below in their own Java // comments
• I remove the definition of the custom tag from build.xml

Let me know if I missed anything.


On 31/08/10 12:33, Vincent Hennebert wrote:
> Hi,
> I just thought I would homogenize our usage of todo tags and match what
> seems to be the de facto standard (“TODO”) among current committers.
> Most @todo indeed come from very old commits. I didn’t realise that
> javadoc could do something with them, which is why that looked to me
> like a minor change that wasn’t needing prior discussion. Sorry about
> that.
> Ok, so there is something that can be done out of @todo tags in javadoc
> comments. Now, having to use our own namespaced version is unfortunate
> and looks overkill to me. Just to have a slightly better formatted
> javadoc? Are such comments of any use to users of the API anyway? Most
> of them rather look like pure internal development issues and should
> probably not even appear in the javadoc.
> Also, while @todo tags can be indexed, modern IDEs can index plain TODO
> tokens as well, so that reduces the advantage of @asf.todo IMO.
> If there are strong feelings against the removal of @asf.todo, I’ll
> revert the change. Otherwise, I’ll actually complete it by removing the
> definition of the custom tag in build.xml, which I hadn’t spotted.
> Vincent
> Simon Pepping wrote:
>> It would indeed have been better to first have a discussion and then
>> make the change. @asf.todo is specific enough that we could have
>> changed it at any time. That said, Glenn's change was also made
>> without a discussion. My javadoc does not complain about the @todo
>> tag, and I had not understood that this was a motivation.
>> The javadoc documentation (of my sun-java6-jdk) is not clear about
>> this topic, and uses @todo liberally in its section about the -tag
>> option. Its most informative paragraph is this:
>> "Avoiding Conflicts - If you want to slice out your own namespace, you
>> can use a dot-separated naming convention similar to that used for
>> packages: com.mycompany.todo. Sun will continue to create standard
>> tags whose names do not contain dots. Any tag you create will override
>> the behavior of a tag by the same name defined by Sun. In other words,
>> if you create a tag or taglet @todo, it will always have the same
>> behavior you define, even if Sun later creates a standard tag of the
>> same name."
>> which does not even go so far as to discourage the @todo tag. It is
>> also not clear how a todo tag would be a specific asf tag, different
>> from the todo tag of any other organization. Everybody uses todo and
>> means the same with it.
>> Using the widely recognized TODO keyword circumvents the tag question
>> altogether, but is outdated since the advent of tags.
>> Let us discuss this and not waste effort on undoing each other's
>> expression of their point of view. Let us also not forget that working
>> in a team requires compromises; the code will never match your own
>> conventions and preferences as precisely as code in your very own
>> project. This is more so in an open project with a long history and a
>> large set of authors.
>> Simon
>> On Sat, Aug 28, 2010 at 09:28:06AM +0800, Glenn Adams wrote:
>>> Vincent,
>>> Could you explain your rationale for this change? Originally, these were all
>>> marked with a non-standard '@todo' javadoc tag, which javadoc complained
>>> about, indicating that for "non-standard" tags, there should be at least one
>>> '.' present in the tag name. I had fixed this by adding the "asf." prefix,
>>> which still allowed tracking these in javadoc more easily. However, your
>>> change now removes the utility of the tag.
>>> On a more general point, wouldn't it be more useful to have a discussion
>>> about stylistic changes prior to implementing them? Just so we can get on
>>> the same page?
>>> Regards,
>>> Glenn
>>> On Fri, Aug 27, 2010 at 9:31 PM, <vhenneb...@apache.org> wrote:
>>>> Author: vhennebert
>>>> Date: Fri Aug 27 13:31:41 2010
>>>> New Revision: 990148
>>>> URL: http://svn.apache.org/viewvc?rev=990148&view=rev
>>>> Log:
>>>> Replaced @asf.todo with normal TODO comment

Reply via email to