[Vm-dev] On community development of the VM's platform code...

[Eliot Miranda]

Hi All,

    this morning I've looked at some platform even t code to address an
issue with scrolling that Chris Muller was bitten by.  In reading the code
I've tried to make the code comprehensible to others who may come to read
it. In particular I changed this code
in platforms/iOS/vm/OSX/sqSqueakOSXApplication+events.m

        evt.charCode = keyCode;
        evt.utf32Code = 0;
        evt.reserved1 = 0;
        evt.modifiers = (CtrlKeyBit | OptionKeyBit | CommandKeyBit |
ShiftKeyBit);
        evt.windowIndex = windowIndex;
        [self pushEventToQueue:(sqInputEvent *) &evt];

to read
        evt.charCode = keyCode;
        evt.utf32Code = 0;
        evt.reserved1 = 0;
       /* Set every meta bit to distinguish the fake event from a real
right/left
        * arrow.
        */
        evt.modifiers = (CtrlKeyBit | OptionKeyBit | CommandKeyBit |
ShiftKeyBit);
        evt.windowIndex = windowIndex;
        [self pushEventToQueue:(sqInputEvent *) &evt];

After all, what the code does is obvious, but /why/ the code does what it
does is not at all obvious.

In reading similar code on the other platforms I see things like this, an
example from platforms/win32/vm/sqWin32Window.c:

      evt->modifiers = CtrlKeyBit;
#ifdef PharoVM
     evt->utf32Code = evt->charCode;
#else
      evt->utf32Code = 0;
#endif
      evt->reserved1 = 0;

Again, *why* the code sets utf32Code but not on Squeak, Newspeak, etc, is
not at all obvious and it would be really helpful if it were commented so
that the decision as to whether the ifdef might be eliminated and the code
always set6 (surely preferable) would be made easier.

The lack of such comments makes managing this code very hard for those of
us that are not platform experts but must maintain the code across all
platforms because that's our lot in life.  The absence of such comments,
when one is struggling to figure out what the hell is going on, feels like
passive aggression ;-)  So if you've made some m modification to the
platform code in the past few years and you haven't commented it to explain
the *why*, please feel free to comment the code and commit or submit a pull
request; it will be warmly appreciated.

Thank you!

_,,,^..^,,,_
best, Eliot
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/vm-dev/attachments/20181107/9628f011/attachment.html>