Henrik Grubbstr?m (Lysator) @ Pike (-) developers forum wrote:
Martin Stjernholm wrote:
"Stephen R. van den Berg" srb@cuci.nl wrote:
Then I thought about what these things are about, and decided that the (in my mind) logical group I'm thinking about all has to do with *hardware* I/O.
Hmm... Maybe the top-level module should be named HW or Hardware then?
Well, that is too broad a term, I think. It does prove a point though: that it is apparently not obvious what hierarchy to put modules/classes in.
So I'm currently implementing USB and OneWire, but I could imagine that other stuff that belongs in this category would be things like: I2C, SPI, 1-Wire, USB, JTAG, MIDI, PC keyboard, UART
(Personally I favor a very flat namespace - the top level is afterall the most convenient one, so let's use it. ;) I've never understood the benefit of Standards.pmod, in particular.)
Well, I can understand both camps. Anyone else got opinions?
Well, I'd prefer not having them at the top-level since they're mostly somewhat unlikely to be used by a random Pike program, and it makes sense to group them together.
That by itself, is not a very strong argument (I think). The most obvious real reason one would want to group them under a hierarchical module name would be to make the list of modules in the autodoc section not too long and too cluttered with modulenames one would be unlikely to use.
I'd say, if, in essence, it's this, then we should solve this by fixing the presentation of the documentation, to allow a topic oriented grouping (next to the linear listing we have now) which should make things easier to find, without actually moving things into submodules.
For the compiler itself, having every module at top level is not a problem at all. Naming conflicts between modules are unlikely as well, and if there would arise any, the module writer(s) are more than capable to think up a logical separation (possibly moving one into a submodule, or simply renaming it) to solve the issue at hand.
This would mean that preferably, modules should become firstclass citizens (i.e. Standards, Protocols and Parser come to mind).
I have to admit that I find it rather tedious and it does *not* improve readability whenever I have to address some library module using submodule addressing. One tends to get rather long names this way, and it takes up a lot of line real-estate; and usually it doesn't add to clarity, since the only name one would be interested in is the last modulename, not any of the prefixes.
Case in point: for the USB module, I have some subclasses called: USB.devices, USB.Iterator, USB.device, USB.transfer
It makes sense to have these four classes, and it makes sense to have them as subclasses from the USB module; it does not really add anything to have to address them as: IO.USB.devices, IO.USB.Iterator, IO.USB.device, IO.USB.transfer
It would clutter the code, but not provide more information to the reader.