On Monday 18 August 2008 07:40, [EMAIL PROTECTED] wrote:
> From: Anant Gole <[EMAIL PROTECTED]>
>
> Signed-off-by: Anant Gole <[EMAIL PROTECTED]>
> ---
>
> Index: linux-davinci-2.6/drivers/net/davinci_emac.c
> ===================================================================
> --- linux-davinci-2.6.orig/drivers/net/davinci_emac.c
> +++ linux-davinci-2.6/drivers/net/davinci_emac.c
> @@ -361,8 +361,8 @@ struct emac_netbufobj {
> struct emac_netpktobj {
> void *pkt_token; /* data token may hold tx/rx chan id */
> struct emac_netbufobj *buf_list; /* array of network buffer objects */
> - int num_bufs; /* number of network buffer objects */
> - int pkt_length; /* packet length (number of bytes) */
> + int num_bufs;
> + int pkt_length;
Looking at this as an example, I do not see how the comments are "redundant".
It is impossible to conclude from the variable name "num_bufs" that it is the
number of network buffer objects.
Removing comments does little to "improve" code - in fact, quite the opposite.
http://www.acmqueue.org/modules.php?name=Content&pa=showpage&pid=290
"When programmers speak of 'self-documenting code', they mean that you should
use techniques such as clear and understandable variable names. Instead of n
or count, it is better to use a readable, self-explanatory name such as
numberOfApricotsPickedToDate. This is a minimalist s documentation.
Nonetheless, it helps the use of explanatory names, whether of variables,
modules, objects, or programs, should be encouraged."
Short form: num_bufs is not adequate documentation.
"I do not use in-line comments, and I discourage their use by programmers who
work with me. If you are going to write a comment, give yourself at least a
full line. Or, better yet, give yourself as much space as you need."
In other words, making this "better" is NOT getting rid of comments (in fact
that makes things WORSE), but going into more detail. This isn't a case
of "style" this is a case of presenting intent to another mind. If you make
it difficult to see intent, you make it difficult to determine if it is a bug
or required.
Had you really wanted to IMPROVE the code, perhaps changing "num_bufs"
to "numberOfNetworkBufferObjects" and then adding documentation throughout
the code would have been better.
But your "patch" seems to serve little purpose. It corrects nothing and
removes detail. I am thus left puzzled at what YOUR intent was for submitting
it?
Cheers,
Lloyd
_______________________________________________
Davinci-linux-open-source mailing list
[email protected]
http://linux.davincidsp.com/mailman/listinfo/davinci-linux-open-source
