Hi,
Felipe Balbi wrote:
> Hi guys,
>
> in order to make our Universal Serial Community more welcoming, we have
> decided to remove unnecessary acronyms from the code. This will be very
> useful for newcomers as they won't have to guess what USB or XHCI means
> and, instead, have it *always* spelled out.
How did this decision come about? If the goal is to attract newcomers, I
doubt more people recognize "universal serial bus" vs "usb".
> I'm sure most of us here have suffered before trying to figure out what
> an acronym means and we all know how much that hinders our hability to
> focus on engineering. Let us all come together under an acronym-free
> drivers/universal_serial_bus (note that renaming of directory will
> happen in future commits after the code is completely cleaned up from
> acronyms).
While I agree that, for some, spelling out the acronym may help, but I
don't think this is the right direction we should be heading.
I can see a few issues with this approach. To list a few:
1) Can you immediately read and recognize this? My brain has to work
extra hard for this:
UNIVERSAL_SERIAL_BUS_UNIVERSAL_HOST_CONTROLLER_INTERFACE_BIG_ENDIAN_DESC
vs
USB_UHCI_BIG_ENDIAN_DESC
2) Backporting fix will be a pain
3) Grep won't be easy
4) Lines over 80 characters (I mean not just because of the screen size,
but I think this is a good guideline to help with readability)
IMHO, spelling out acronym should be in the documentation. Somehow, I
doubt that newcomers reading this code will now have an "Aha!" moment
and start to learn/contribute.
Did we explore other ways to approach this? (such as adding more
documentations where needed, and more sample codes?)
>
> Granted, the patches are a little big, but I think they can still be
> squeezed during the merge window since there are no functional changes.
>
> Felipe Balbi (7):
> universal serial bus: remove acronyms
> open host controller interface: remove acronyms
> universal host controller interface: remove acronyms
> enhanced host controller interface: remove acronyms
> extensible host controller interface: remove acronyms
> designware cores universal serial bus3: remove acronyms
> designware cores universal serial bus2: remove acronyms
>
>
BR,
Thinh
