[wp-hackers] Proposal for a function commenting convention

[Travis Snoozy]

On Tue, 16 Oct 2007 09:03:21 +0100 (BST), "Peter Westwood"
<peter.westwood at ftwr.co.uk> wrote:

> 
> On Tue, October 16, 2007 1:51 am, Jacob wrote:
> > Agreed. I'll update the patches.
> >
> > I have some more questions.
> >
> > I think a compromise between Travis and me would be that we include
> > both what functions should do along with what it does do. This will
> > give optimal information on what to expect in both what the
> > function does and what it actually does. In going over the
> > plugins.php phpdoc, I did just this. I found that using the @see
> > http://trac.wordpress.org/ticket/{Ticket number of bug} in that, in
> > the likely chance that the bug is fixed, the reader would know by
> > looking at the trac ticket.
> >
> > The second is that I haven't reached a conclusion on short
> > description format.
> >
> > /**
> >  * function_name() - short description
> >
> > or
> >
> > /**
> >  * short description
> >
> > Plugins.php uses the second, while taxonomy.php (the phpdoc that I
> > wrote) uses the first.
> >
> 
> My vote would be for the first - Adding the function_name() as well
> feels like unnecessary duplication.

Theoretically, I concur with you. In practice, I find that having the
function name is really useful when reading these comments in the
source, especially if the comments are more than a screen worth of text.
Even when I can see the function line, I wind up scanning down and up
to match the documentation with the function name, and it tends to
break my flow of focus. Naturally, this is only an issue when reading
the comments in-line with the code -- but again, in practice, that's
where I usually read these.


-- 
Travis 

In Series maintainer
Random coder & quality guy
<http://remstate.com/>