[RFC]: field name identifier conventions

[RFC]: field name identifier conventions

[Gerrit Renker]

I have a question/suggestion for DCCP/CCID field names, which have a tendency to grow
into really_quite_long_strings. The convention for field members seems to be


	"x"->"x"_<fieldname>

Examples are in particular

   * hctx->ccid2hctx_<fieldname>
   * hcrx->ccid3hcrx_<fieldname>
   * avr->dccpavr_<fieldname>
   * av->dccpav_<fieldname>

The problem is that this naming convention has no apparent benefits: 
  
  * which struct is used is evident from the context and need not be encoded
  * someone reading the code is only interested in the fieldnames
  * with the line length limit of 80 characters this convention almost inevitably leads to
    multi-line expression for even the simplest kinds of comparisons and expressions.

Hence my suggestion is to reduce the replicated "x" field prefix, so that field members become
shorter, as will be expressions, and the code would be easier to read.

What is the opinion of other developers / maintainer regarding this? 

Re: [RFC]: field name identifier conventions

[Arnaldo Carvalho de Melo]

Em Sat, Oct 20, 2007 at 04:54:35PM +0100, Gerrit Renker escreveu:
> I have a question/suggestion for DCCP/CCID field names, which have a tendency to grow
> into really_quite_long_strings. The convention for field members seems to be
> 
> 
> 	"x"->"x"_<fieldname>
> 
> Examples are in particular
> 
>    * hctx->ccid2hctx_<fieldname>
>    * hcrx->ccid3hcrx_<fieldname>
>    * avr->dccpavr_<fieldname>
>    * av->dccpav_<fieldname>
> 
> The problem is that this naming convention has no apparent benefits: 
>   
>   * which struct is used is evident from the context and need not be encoded
>   * someone reading the code is only interested in the fieldnames
>   * with the line length limit of 80 characters this convention almost inevitably leads to
>     multi-line expression for even the simplest kinds of comparisons and expressions.
> 
> Hence my suggestion is to reduce the replicated "x" field prefix, so that field members become
> shorter, as will be expressions, and the code would be easier to read.
> 
> What is the opinion of other developers / maintainer regarding this? 

Well, while I agree that the names being overly long its a nuisance at
the same time being able to grep for some specific field is really nice
and was the intention.

Long ago DaveM accepted patches for struct sock, but then there its just
->sk_FIELD_NAME, not 10 characters like in the ccids case. struct inode
fields predate that even, but then its just ->i_FIELD_NAME.

I think that providing a unique namespace for struct member names is ok
if it doesn't get that long (mea culpa in the aforementioned cases 8)).

- Arnaldo

Re: [RFC]: field name identifier conventions

[Arnaldo Carvalho de Melo]

Em Sat, Oct 20, 2007 at 07:03:49PM -0200, Arnaldo Carvalho de Melo escreveu:
> Em Sat, Oct 20, 2007 at 04:54:35PM +0100, Gerrit Renker escreveu:
> > I have a question/suggestion for DCCP/CCID field names, which have a tendency to grow
> > into really_quite_long_strings. The convention for field members seems to be
> > 
> > 
> > 	"x"->"x"_<fieldname>
> > 
> > Examples are in particular
> > 
> >    * hctx->ccid2hctx_<fieldname>
> >    * hcrx->ccid3hcrx_<fieldname>
> >    * avr->dccpavr_<fieldname>
> >    * av->dccpav_<fieldname>
> > 
> > The problem is that this naming convention has no apparent benefits: 
> >   
> >   * which struct is used is evident from the context and need not be encoded
> >   * someone reading the code is only interested in the fieldnames
> >   * with the line length limit of 80 characters this convention almost inevitably leads to
> >     multi-line expression for even the simplest kinds of comparisons and expressions.
> > 
> > Hence my suggestion is to reduce the replicated "x" field prefix, so that field members become
> > shorter, as will be expressions, and the code would be easier to read.
> > 
> > What is the opinion of other developers / maintainer regarding this? 
> 
> Well, while I agree that the names being overly long its a nuisance at
> the same time being able to grep for some specific field is really nice
> and was the intention.
> 
> Long ago DaveM accepted patches for struct sock, but then there its just
> ->sk_FIELD_NAME, not 10 characters like in the ccids case. struct inode
> fields predate that even, but then its just ->i_FIELD_NAME.
> 
> I think that providing a unique namespace for struct member names is ok
> if it doesn't get that long (mea culpa in the aforementioned cases 8)).

Forgot to leave a suggestion for the mentioned case: ->c2tx_ perhaps :)

- Arnaldo

P.S.: What we really needed was more intelligent grep, ctags
replacements for quickly locating such information in C source files,
perhaps one that could understand types and then could allow developers
to ask questions like "show me all the places where the field foo of
type bar appears", but till then the old practice, albeit not uniformly
used of using a namespace alias in the form of a prefix seems to suit us
:-)

Re: [RFC]: field name identifier conventions

[Ian McDonald]

On 10/21/07, Gerrit Renker <gerrit@erg.abdn.ac.uk> wrote:
> I have a question/suggestion for DCCP/CCID field names, which have a tendency to grow
> into really_quite_long_strings. The convention for field members seems to be
>
>
>         "x"->"x"_<fieldname>
>
> Examples are in particular
>
>    * hctx->ccid2hctx_<fieldname>
>    * hcrx->ccid3hcrx_<fieldname>
>    * avr->dccpavr_<fieldname>
>    * av->dccpav_<fieldname>
>
> The problem is that this naming convention has no apparent benefits:
>
>   * which struct is used is evident from the context and need not be encoded
>   * someone reading the code is only interested in the fieldnames
>   * with the line length limit of 80 characters this convention almost inevitably leads to
>     multi-line expression for even the simplest kinds of comparisons and expressions.
>
> Hence my suggestion is to reduce the replicated "x" field prefix, so that field members become
> shorter, as will be expressions, and the code would be easier to read.
>
> What is the opinion of other developers / maintainer regarding this?
>
I agree with you totally.

I think the best way to do this is once Arnaldo agrees and then
prepare a big patch to do this. If we don't get Arnaldo's buy in then
it will be hell to maintain the patch set. This approach will still be
a pain as you'll probably have to redo your exisiting patches but it
is better to do it once then multiple times.

Ian
-- 
Web1: http://wand.net.nz/~iam4/
Web2: http://www.jandi.co.nz
Blog: http://iansblog.jandi.co.nz

Re: [RFC]: field name identifier conventions

[Łeandro Sales]

2007/10/20, Arnaldo Carvalho de Melo <acme@ghostprotocols.net>:
> Em Sat, Oct 20, 2007 at 07:03:49PM -0200, Arnaldo Carvalho de Melo escreveu:
> > Em Sat, Oct 20, 2007 at 04:54:35PM +0100, Gerrit Renker escreveu:
> > > I have a question/suggestion for DCCP/CCID field names, which have a tendency to grow
> > > into really_quite_long_strings. The convention for field members seems to be
> > >
> > >
> > >     "x"->"x"_<fieldname>
> > >
> > > Examples are in particular
> > >
> > >    * hctx->ccid2hctx_<fieldname>
> > >    * hcrx->ccid3hcrx_<fieldname>
> > >    * avr->dccpavr_<fieldname>
> > >    * av->dccpav_<fieldname>
> > >
> > > The problem is that this naming convention has no apparent benefits:
> > >
> > >   * which struct is used is evident from the context and need not be encoded
> > >   * someone reading the code is only interested in the fieldnames
> > >   * with the line length limit of 80 characters this convention almost inevitably leads to
> > >     multi-line expression for even the simplest kinds of comparisons and expressions.
> > >
> > > Hence my suggestion is to reduce the replicated "x" field prefix, so that field members become
> > > shorter, as will be expressions, and the code would be easier to read.
> > >
> > > What is the opinion of other developers / maintainer regarding this?
> >
> > Well, while I agree that the names being overly long its a nuisance at
> > the same time being able to grep for some specific field is really nice
> > and was the intention.
> >
> > Long ago DaveM accepted patches for struct sock, but then there its just
> > ->sk_FIELD_NAME, not 10 characters like in the ccids case. struct inode
> > fields predate that even, but then its just ->i_FIELD_NAME.
> >
> > I think that providing a unique namespace for struct member names is ok
> > if it doesn't get that long (mea culpa in the aforementioned cases 8)).
>
> Forgot to leave a suggestion for the mentioned case: ->c2tx_ perhaps :)
>
> - Arnaldo
>
> P.S.: What we really needed was more intelligent grep, ctags
> replacements for quickly locating such information in C source files,
> perhaps one that could understand types and then could allow developers
> to ask questions like "show me all the places where the field foo of
> type bar appears", but till then the old practice, albeit not uniformly
> used of using a namespace alias in the form of a prefix seems to suit us
> :-)
> -
> To unsubscribe from this list: send the line "unsubscribe dccp" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>

I think the arnaldo comments sounds appropriate. Particular for me,
the current nomenclature helped me in the fork from ccid3 to ccid4.
While reviewing the code (or search for something specific, like
arnaldo commented out) just having "hctx->last_counter" instead of
"hctx->ccid4hcrx_last_counter" in some cases will make us have to
backward to a certain parts of the code in order to understand if the
hctx was returned by a call to ccid3_hc_rx_sk() function, to the
ccid4_hc_rx_sk() function or by the new function that I will suggest
to you soon named ccid34_hc_rx_sk(), which will be a shared function
used by both, ccid3 and ccid4.

Well, I don't know if my comments make sense or not, mainly because
I'm new in the dccp hacking, but this is my opinion.  What about
follow the arnaldo suggestion, have something like
"hctx->c4_last_counter" rather than "hctx->ccid4hcrx_last_counter". In
this case, if we need to make a search for foo of type bar, we can
search for the string "tx->c4", or "rx->c4" (just a very specific
example):

# grep -r "tx->c4" *

Leandro.

Re: [RFC]: field name identifier conventions

[Tommi Saviranta]

On Sat, Oct 20, 2007 at 18:39:23 +0300, Gerrit Renker wrote:
> I have a question/suggestion for DCCP/CCID field names, which have a
> tendency to grow into really_quite_long_strings. The convention for
> field members seems to be
> 
> 	"x"->"x"_<fieldname>

> The problem is that this naming convention has no apparent benefits: 
>   
>   * which struct is used is evident from the context and need not be
>     encoded
>   * someone reading the code is only interested in the fieldnames

I think reusing bits from structure name in field names is partly
traditional, partly ignorant. When I first took a look at DCCP's code, I
found the "x_" prefix somewhat explanatory, but it soon became annoyance
I would just have to live with.

> Hence my suggestion is to reduce the replicated "x" field prefix, so
> that field members become shorter, as will be expressions, and the
> code would be easier to read.
> 
> What is the opinion of other developers / maintainer regarding this? 

I agree, the prefixes are unnecessary.

Re: [RFC]: field name identifier conventions

[Gerrit Renker]

Thanks everyone for replying, below is the summary of earlier emails.


1) Ian wrote:
|  I think the best way to do this is once Arnaldo agrees and then
|  prepare a big patch to do this. If we don't get Arnaldo's buy in then
|  it will be hell to maintain the patch set. 
Fully agree - Arnaldo is the maintainer and as such it is up to him to decide on such things
affecting global consistency. If there is a new naming scheme which finds his approval, I am
more than happy to update the entire test tree, but if not I wouldn't like to change
the patches: these should reflect the existing DCCP style/conventions.

2) All agreed that the naming scheme could be changed.

3) There are the following suggestions:
   * Arnaldo: "->c2tx_"
   * Leandro: "tx->c4"

  If we combine these suggestions, considering that for the CCID sockets this will be likely
  `hcrx' for RX sockets and `hctx' for TX sockets (like referring to struct sk_buff as skb),
  then Leandro's scheme is nice and small:

	* hcrx->c3_last_counter
	* hcrx->c4_last_counter
	* hctx->c3_last_win_count
	* hctx->c4_no_feedback_timer

  In conclusion, what about the following naming scheme:?

	* hctx->c"N"_FIELDNAME		/* N = CCID number, 0..255 */
	* hcrx->c"N"_FIELDNAME
	*  avr->avr_FIELDNAME		/* r for record ? */
	*   av->av_FIELDNAME		/* or drop the `av/avr' ? */

  The actual patch will probably cost less work than making this scheme consistent.