[Axis2] Conventions for task-related comments?

[Bill Nagy <na...@watson.ibm.com>]

Hi folks,

As I wander through the code, I'm adding comments where
appropriate/missing.  Are you following any particular conventions for
task-related comments (e.g. //TODO: (<username>) <comment>, //FIXME:
(<username>) <comment>, //REVIEW: (<username>) <comment>, //JAVADOC:
(<username>) <comment>, etc. ?)

-Bill

Re: [Axis2] Conventions for task-related comments?

[Glen Daniels <gl...@thoughtcraft.com>]

Hi Chinthaka, all:

> Do we wanna have explicit guidelines for coding ? Hmm, I don't think so.
> So far coding seems ok, at least for me. Why restrict people in open
> source :).

Because it makes life easier when everyone standardizes sometimes.  You 
know, like SOAP and WSDL! :)  If everyone is using different conventions 
for "needs work", then you can't rely on your IDE or a grep through the 
code to turn up places that might be valuable to work on.

Coding conventions are IMHO a good thing in a project.

>> BTW we are not into putting user names/author names in the code!

With things like TODO/FIXME, I think it's actually OK (though certainly 
not necessary) to put names in.  The main reason not to put @author tags 
in class JavaDocs is that the whole file often gets worked on by 
multiple people and the concept of "owner" doesn't make sense after a 
while.  With a TODO, it's generally a much smaller task limited to a 
particular area of the code and it can be nice to see who is the major 
stakeholder in this particular area without digging through commit logs.

--Glen

Re: [Axis2] Conventions for task-related comments?

[Eran Chinthaka <ch...@opensource.lk>]

Ajith Ranabahu wrote:
> Hi all,
> Just as Glen said I (and most of the others too) use the //todo as a
> flag but none of the other mentioned. I'm happy to have a convention
> though

Most of the guys followed some conventions with regards to TODO, even
though none of them were ever documented.
For example, we put //TODO s most of the time.

Do we wanna have explicit guidelines for coding ? Hmm, I don't think so.
So far coding seems ok, at least for me. Why restrict people in open
source :).


> BTW we are not into putting user names/author names in the code!

If this was there, it could have been easier to catch the relevant
person :).

-- Chinthaka

Re: [Axis2] Conventions for task-related comments?

[Bill Nagy <na...@watson.ibm.com>]

I wasn't trying to force my conventions on anyone; I was just trying to
make sure that I wasn't doing the same thing differently for no reason.

I put my userid in the actionable comments solely for the purpose of
identifying that I wrote them.  That way if someone else reads them and
doesn't understand why they say what they say, they know who to ask for
clarification.  (You can always dig through the log messages; it's just
a pain to do so.)

I use more than a TODO, simply for the sake of making it easier to
filter with an IDE or grep.  Here's what the different tags mean:

TODO: Identifies a missing or incomplete section of code.
FIXME: Identifies temporary/broken code.  (This type of code is
sometimes put in place as a stopgap just to get things working.)
REVIEW: Identifies code that may need further review.
JAVADOC: Identifies missing or incomplete JAVADOC.

-Bill 

On Mon, 2006-04-17 at 10:57 +0600, Ajith Ranabahu wrote:
> Hi all,
> Just as Glen said I (and most of the others too) use the //todo as a
> flag but none of the other mentioned. I'm happy to have a convention
> though
> BTW we are not into putting user names/author names in the code!
> 
> On 4/17/06, Glen Daniels <gl...@thoughtcraft.com> wrote:
> > I tend to use at least //TODO: and //FIXME: (which IDEA also recognizes
> > and flags).  I'd be +1 for getting team buy-in for these conventions...
> >
> > --Glen
> >
> > Davanum Srinivas wrote:
> > > Nope. We are in the wild-wild-west :)
> > >
> > > On 4/14/06, Bill Nagy <na...@watson.ibm.com> wrote:
> > >> Hi folks,
> > >>
> > >> As I wander through the code, I'm adding comments where
> > >> appropriate/missing.  Are you following any particular conventions for
> > >> task-related comments (e.g. //TODO: (<username>) <comment>, //FIXME:
> > >> (<username>) <comment>, //REVIEW: (<username>) <comment>, //JAVADOC:
> > >> (<username>) <comment>, etc. ?)
> >
> 
> 
> --
> Ajith Ranabahu

Re: [Axis2] Conventions for task-related comments?

[Ajith Ranabahu <aj...@gmail.com>]

Hi all,
Just as Glen said I (and most of the others too) use the //todo as a
flag but none of the other mentioned. I'm happy to have a convention
though
BTW we are not into putting user names/author names in the code!

On 4/17/06, Glen Daniels <gl...@thoughtcraft.com> wrote:
> I tend to use at least //TODO: and //FIXME: (which IDEA also recognizes
> and flags).  I'd be +1 for getting team buy-in for these conventions...
>
> --Glen
>
> Davanum Srinivas wrote:
> > Nope. We are in the wild-wild-west :)
> >
> > On 4/14/06, Bill Nagy <na...@watson.ibm.com> wrote:
> >> Hi folks,
> >>
> >> As I wander through the code, I'm adding comments where
> >> appropriate/missing.  Are you following any particular conventions for
> >> task-related comments (e.g. //TODO: (<username>) <comment>, //FIXME:
> >> (<username>) <comment>, //REVIEW: (<username>) <comment>, //JAVADOC:
> >> (<username>) <comment>, etc. ?)
>


--
Ajith Ranabahu

Re: [Axis2] Conventions for task-related comments?

[Glen Daniels <gl...@thoughtcraft.com>]

I tend to use at least //TODO: and //FIXME: (which IDEA also recognizes 
and flags).  I'd be +1 for getting team buy-in for these conventions...

--Glen

Davanum Srinivas wrote:
> Nope. We are in the wild-wild-west :)
> 
> On 4/14/06, Bill Nagy <na...@watson.ibm.com> wrote:
>> Hi folks,
>>
>> As I wander through the code, I'm adding comments where
>> appropriate/missing.  Are you following any particular conventions for
>> task-related comments (e.g. //TODO: (<username>) <comment>, //FIXME:
>> (<username>) <comment>, //REVIEW: (<username>) <comment>, //JAVADOC:
>> (<username>) <comment>, etc. ?)

Re: [Axis2] Conventions for task-related comments?

[Davanum Srinivas <da...@gmail.com>]

Nope. We are in the wild-wild-west :)

On 4/14/06, Bill Nagy <na...@watson.ibm.com> wrote:
> Hi folks,
>
> As I wander through the code, I'm adding comments where
> appropriate/missing.  Are you following any particular conventions for
> task-related comments (e.g. //TODO: (<username>) <comment>, //FIXME:
> (<username>) <comment>, //REVIEW: (<username>) <comment>, //JAVADOC:
> (<username>) <comment>, etc. ?)
>
> -Bill
>
>
>


--
Davanum Srinivas : http://wso2.com/blogs/