Re: [PATCH net-next v2 1/9] net: ethernet: implement OPEN Alliance control transaction interface

[Andrew Lunn]

> Still if you feel like using "write" instead of "wnr" and "protect" 
> instead of "prote", I will change them in the next revision.

There is some value in using names from the standard, if they are
actually good names. But i guess most developers don't have a copy of
the standard by there side. 

You actually wrote in the patch:

+/* Control header */
+#define CTRL_HDR_DNC           BIT(31)         /* Data-Not-Control */
+#define CTRL_HDR_HDRB          BIT(30)         /* Received Header Bad */
+#define CTRL_HDR_WNR           BIT(29)         /* Write-Not-Read */
+#define CTRL_HDR_AID           BIT(28)         /* Address Increment Disable */
+#define CTRL_HDR_MMS           GENMASK(27, 24) /* Memory Map Selector */

The comments suggest you also don't think the names are particularly
good, otherwise you would not of added comments.

But if you instead had:

/* Control header */
#define CTRL_HDR_DATA_NOT_CTRL           BIT(31)
#define CTRL_HDR_HDR_RX_BAD              BIT(30)
#define CTRL_HDR_WRITE           	 BIT(29)
#define CTRL_HDR_ADDR_INC_DISABLE        BIT(28)
#define CTRL_HDR_MEM_MAP_SELECTOR        GENMASK(27, 24)

the names are probably sufficient that comments are not needed.  And
is should be easy for somebody to map these back to the names used in
the standard.

This also to some extent comes into the comment about coding style, a
function does one thing, is short, etc. Short functions tend to have
less indentation, meaning you can use longer names. And longer names
are more readable, making the function easier to understand, so it
does that one thing well.

    Andrew