Page MenuHomePhabricator

C#: Event naming
Closed, ResolvedPublic

Description

  1. Event naming
    • Now : IdleEnterEvt
    • Suggested : IdleEntered (past tense without Evt)
lauromoura triaged this task as High priority.

This could be kinda tricky to do in a generic way. We may end up having to build a list of irregular verbs and their past tense in order to generate them.

About documentation too, we would need to guarantee that the docs use eolian references to properly translate them (although this also happens with the current naming scheme).

Here is a list of generated events from the C# files. (without the prefix).

The majority of them are already in the past tense.

Aborted
AccessChanged
AccessSelectionChanged
AccessTextCaretMoved
AccessTextInserted
AccessTextRemoved
AccessTextSelectionChanged
ActiveDescendantChanged
Added
AnchorDown
AnchorHoverOpened
AnchorIn
AnchorOut
AnchorUp
AnimateBegin
AnimateDone
AnimatorTick
Arguments
BackwallClicked
BarDrag
BarHide
BarPosChanged
BarPress
BarShow
BarSizeChanged
BarUnpress
BoundsChanged
Buffer
ButtonClicked
CanReadChanged
CanWriteChanged
Changed
ChangedUser
ChildAdded
ChildFocusChanged
ChildRemoved
ChildrenChanged
ChildrenCountChanged
CircularDependency
ClickedAny
Clicked
Closed
ContentAdded
ContentChanged
ContentMinSizeChanged
ContentRemoved
ContentSizeChanged
ContextOpen
Contracted
CoordsDirty
Created
CursorChanged
CursorChangedManual
DeleteRequest
Del
Destruct
DeviceAdded
DeviceChanged
DeviceRemoved
DirtyLogicFreezeChanged
DownloadDone
DownloadError
DownloadProgress
DownloadStart
DragAccept
DragDone
DragDrop
DragEnd
DragEnter
Drag
DragLeave
DragPos
DragStartDown
DragStart
DragStartLeft
DragStartRight
DragStartUp
DragStop
Drop
EdgeDown
EdgeLeft
EdgeRight
EdgeUp
ElmActionBlockMenu
Ended
Eos
Error
EvtWithArray
EvtWithBool
EvtWithByte
EvtWithChar
EvtWithDouble
EvtWithError
EvtWithFloat
EvtWithInt16
EvtWithInt32
EvtWithInt64
EvtWithInt8
EvtWithInt
EvtWithLlong
EvtWithObj
EvtWithShort
EvtWithString
EvtWithStructComplex
EvtWithStruct
EvtWithUbyte
EvtWithUint16
EvtWithUint32
EvtWithUint64
EvtWithUint8
EvtWithUint
EvtWithUllong
EvtWithUnder
EvtWithUshort
Expanded
ExpandStateChanged
FingerDown
FingerMove
FingerUp
FlushPre
FocusChanged
FocusGeometryChanged
FocusIn
FocusManagerChanged
FocusOut
FocusParentChanged
FullscreenChanged
GestureDoubleTap
GestureFlick
GestureLongTap
GestureMomentum
GestureTap
GestureTripleTap
GestureZoom
HintsChanged
Hold
IdleEnter
Idle
IdleExit
ImagePreload
ImageResize
ImageUnload
IndicatorPropChanged
Invalidate
ItemAdded
ItemClickedAny
ItemClicked
ItemDeleted
ItemFocused
ItemHighlighted
ItemLongpressed
ItemPressed
ItemRealized
ItemSelected
ItemUnfocused
ItemUnhighlighted
ItemUnpressed
ItemUnrealized
ItemUnselected
KeyDown
KeyUp
LanguageChanged
LayoutUpdated
LoadDetail
LoadDone
LoadedDetail
Loaded
LoadError
Load
Longpressed
ManagerFocusChanged
MaximizedChanged
MaxReached
MemberAdded
MemberRemoved
Message
MessageFuture
Minimized
MinReached
ModelChanged
Nonconflicted
Noref
Normal
ObjectFocusIn
ObjectFocusOut
OwnershipShared
OwnershipUnique
PanContentChanged
PanPositionChanged
PanViewportChanged
PartInvalid
Pause
PointerAxis
PointerCancel
PointerDown
PointerIn
PointerMove
PointerOut
PointerUp
PointerWheel
PollHigh
PollLow
PollMedium
PositionChanged
PosUpdate
PreeditChanged
Prepare
Pressed
Press
ProfileChanged
PropertiesChanged
PropertyBound
PropertyChanged
Quit
Read
Recalc
RedirectChanged
RedoRequest
Removed
RenderPost
RenderPre
Repeated
Resume
Running
SceneFocusIn
SceneFocusOut
ScrollAnimStart
ScrollAnimStop
ScrollDown
ScrollDragStart
ScrollDragStop
Scroll
ScrollLeft
ScrollRight
ScrollStart
ScrollStop
ScrollUp
SelectedChanged
Selected
SelectionChanged
SelectionCleared
SelectionCopy
SelectionCut
SelectionPaste
SelectionStart
SignalHup
SignalUsr1
SignalUsr2
SizeChanged
SliderDragStart
SliderDragStop
StackingChanged
Standby
Started
StateChanged
Steady
Stick
StyleInsetsChanged
TabChanged
Terminate
TextSelectionChanged
ThemeChanged
Timeout
TimerTick
Toggled
TransitionEnd
TransitionStart
UndoRequest
Unpressed
Unpress
Unselected
Unstick
Validate
ValueChanged
VisibilityChanged
VisibleDataChanged
VisibleRangeChanged
WindowActivated
WindowCreated
WindowDeactivated
WindowDestroyed
WindowMaximized
WindowMinimized
WindowRestored
WinRotationChanged
Withdrawn
WmRotationChanged
WmSelectionChanged
Write
ZoomChange
ZoomStart
ZoomStop

From C# guidelines in https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/names-of-type-members#names-of-events:

Names of Events
Events always refer to some action, either one that is happening or one that has occurred. Therefore, as with methods, events are named with verbs, and verb tense is used to indicate the time when the event is raised.

✓ DO name events with a verb or a verb phrase.
Examples include Clicked, Painting, DroppedDown, and so on.

✓ DO give events names with a concept of before and after, using the present and past tenses.
For example, a close event that is raised before a window is closed would be called Closing, and one that is raised after the window is closed would be called Closed.

X DO NOT use "Before" or "After" prefixes or postfixes to indicate pre- and post-events. Use present and past tenses as just described.

✓ DO name event handlers (delegates used as types of events) with the "EventHandler" suffix, as shown in the following example:
public delegate void ClickedEventHandler(object sender, ClickedEventArgs e);

✓ DO use two parameters named sender and e in event handlers.
The sender parameter represents the object that raised the event. The sender parameter is typically of type object, even if it is possible to employ a more specific type.

✓ DO name event argument classes with the "EventArgs" suffix.

Trying to automatically convert eo event names to verbs in the past tense is going to be an nightmare :)
All events should already be like that (as shown in the list above), and the rest should be renamed in the eo file.

Adding the Evt suffix protects us from name clashes between events and properties, for example. We already use a I prefix for interfaces and there's talk of using C for classes so Evt does not look very bad to me.

Trying to automatically convert eo event names to verbs in the past tense is going to be an nightmare :)

Indeed.

.... and there's talk of using C for classes ...

Is there? O_o

So, in the discussion of D9692, we came up with the suggestion to replace the evt prefix with Event.

Current scheme:

  • button.ClickedEvt += (object sender, ClickableClickedEvt_Args args) {...};

D9692:

  • button.ClickedEvt += (object sender, ClickableClickedEvtEventArgs args) {...};

Event proposal

  • button.ClickedEvent += (object sender, ClickableClickedEventArgs args) {...};

.... and there's talk of using C for classes ...

Is there? O_o

Well... I suggested it in D9569#178188, maybe we can think about taking it more seriously... ?

brunobelo closed this task as Resolved.Sep 13 2019, 6:46 AM