: field name identifier conventions
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?
Em Sat, Oct 20, 2007 at 04:54:35PM +0100, Gerrit Renker escreveu:
Quoted 20 lines
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.
Quoted 4 lines
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
Em Sat, Oct 20, 2007 at 07:03:49PM -0200, Arnaldo Carvalho de Melo escreveu:
Quoted 30 lines
Em Sat, Oct 20, 2007 at 04:54:35PM +0100, Gerrit Renker escreveu:
Quoted 20 lines
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.Quoted 4 lines
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.
Quoted 6 lines
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 :-)
Quoted 20 lines · 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.
Quoted 5 lines
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
Signature · 3 lines
Web1: http://wand.net.nz/~iam4/ Web2: http://www.jandi.co.nz Blog: http://iansblog.jandi.co.nz
2007/10/20, Arnaldo Carvalho de Melo <[email protected]>:
Quoted 42 lines
Em Sat, Oct 20, 2007 at 07:03:49PM -0200, Arnaldo Carvalho de Melo escreveu:
Quoted 30 lines
Em Sat, Oct 20, 2007 at 04:54:35PM +0100, Gerrit Renker escreveu:
Quoted 20 lines
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.Quoted 4 lines
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.
Quoted 6 lines
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
Quoted 12 lines
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 [email protected]
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.
Quoted 11 lines · 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>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.
Quoted 5 lines
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.
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.