for what it's worth, i don't have a strong opinion on this issue (i.e., whether to use @asf.todo or TODO); i explained below why i made the original change, and, yes, it was not discussed at the time;
the point i was making below, which you echo, is that is indeed better to first discuss a change that undoes a set of changes than to slip it by, perhaps unnoticed; in the future, were i to be granted committer status, i certainly would not want to simply commit a change that undoes the work of another committer, at least without some discussion and consensus taking; g. On Sat, Aug 28, 2010 at 4:51 PM, Simon Pepping <[email protected]>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, <[email protected]> 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 > > > > > > > > -- > Simon Pepping > home page: http://www.leverkruid.eu >
