update names per naming guidelines. #1012

Merged
merged 7 commits into from Sep 8, 2016

Projects

None yet

6 participants

@BillWagner
Collaborator

Fixes #1011

The section on "events" incorrectly recommended naming events with the "On" prefix. Events should be the verb or verb phrase, and the handlers should have the "On" prefix.

@BillWagner BillWagner update names per naming guidelines.
c62dc2f
@BillWagner
Collaborator

Hmmm. OPS build didn't happen. closing and reopening.

@BillWagner BillWagner closed this Sep 7, 2016
@BillWagner BillWagner reopened this Sep 7, 2016
@BillWagner BillWagner closed this Sep 7, 2016
@BillWagner BillWagner reopened this Sep 7, 2016
@qinezh
Collaborator
qinezh commented Sep 7, 2016

Open Publishing Build Service: The pull request content has been published and here are some sample preview links:

@BillWagner BillWagner Fix one paragraph of text
87bd2e9
@qinezh
Collaborator
qinezh commented Sep 7, 2016

Open Publishing Build Service: The pull request content has been published and here are some sample preview links:

@svick svick commented on an outdated diff Sep 7, 2016
docs/csharp/event-pattern.md
@@ -126,15 +126,15 @@ that the event objects can only be accessed in safe ways. The only
operations available on a field-like event are add handler:
```cs
-EventHandler<FileFoundArgs> handler = (sender, eventArgs) =>
+EventHandler<FileFoundArgs> OnFoundFile = (sender, eventArgs) =>
@svick
svick Sep 7, 2016 edited Contributor

This is a local variable, so it should use camelCase, not PascalCase.

@svick svick commented on an outdated diff Sep 7, 2016
docs/csharp/event-pattern.md
@@ -221,7 +221,7 @@ Let's update the subscriber so that it requests a cancellation once
it finds the first executable:
```cs
-EventHandler<FileFoundArgs> handler = (sender, eventArgs) =>
+EventHandler<FileFoundArgs> OnFoundFile = (sender, eventArgs) =>
@svick
svick Sep 7, 2016 Contributor

This is a local variable too, so it should also use camelCase.

@svick svick commented on an outdated diff Sep 7, 2016
docs/csharp/event-pattern.md
@@ -270,7 +270,7 @@ need extra code in those handlers in this project, but this shows how
you would create them.
```cs
-internal event EventHandler<SearchDirectoryArgs> OnChangeDirectory
+internal event EventHandler<SearchDirectoryArgs> ChangeDirectory
@svick
svick Sep 7, 2016 edited Contributor

Wouldn't DirectoryChanged be a better name? It would also be more consistent with FoundFile and the guideline in events-overview to use past tense.

Also, why is changeDirectory just below a private event? Wouldn't a field be enough? (The text below also mentions that it's a field, when it's not currently.)

@svick svick commented on an outdated diff Sep 7, 2016
docs/csharp/events-overview.md
@@ -93,15 +93,18 @@ when there are no subscribers to that event.
You subscribe to an event by using the `+=` operator:
```cs
-EventHandler<FileListArgs> handler = (sender, eventArgs) =>
+EventHandler<FileListArgs> OnProgress = (sender, eventArgs) =>
@svick
svick Sep 7, 2016 Contributor

One more local variable that should use camelCase.

@svick svick commented on an outdated diff Sep 7, 2016
docs/csharp/distinguish-delegates-events.md
@@ -48,7 +48,7 @@ properly sort the elements. LINQ queries must be supplied with delegates
in order to determine what elements to return. Both used a design built
with delegates.
-Consider the `OnProgress` event handler. It reports progress on a task.
+Consider the `Progress` event handler. It reports progress on a task.
@svick
svick Sep 7, 2016 edited Contributor

Should this be "the Progress event"? I think this paragraph talks about the event itself, not about some specific event handler subscribed to it.

@BillWagner BillWagner Respond to feedback
@svick provides the usual very thorough review.
61b23cf
@qinezh
Collaborator
qinezh commented Sep 7, 2016

Open Publishing Build Service: The pull request content has been published and here are some sample preview links:

@BillWagner BillWagner one final bit of feedback.
52809ed
@qinezh
Collaborator
qinezh commented Sep 7, 2016

Open Publishing Build Service: The pull request content has been published and here are some sample preview links:

@mairaw mairaw commented on an outdated diff Sep 7, 2016
docs/csharp/events-overview.md
```
The type of the event (`EventHandler<FileListArgs>` in this example) must be a
delegate type. There are a number of conventions that you should follow
when declaring an event. Typically, the event delegate type has a void return.
-Prefix event declarations with 'On'.
-The remainder of the name is a verb. Use past tense (as in this example) when
+Event declarations should be a verb, or verb phrase.
@mairaw
mairaw Sep 7, 2016 Collaborator

nit: or a verb phrase

@mairaw mairaw commented on an outdated diff Sep 7, 2016
docs/csharp/events-overview.md
present tense indicates that the event supports cancellation. For example,
-an `OnClosing` event may include an argument that would indicate if the close
+an `Closing` event may include an argument that would indicate if the close
@mairaw
mairaw Sep 7, 2016 Collaborator

an Closing -> a Closing

@mairaw mairaw and 1 other commented on an outdated diff Sep 7, 2016
samples/csharp/events/Program.cs
@@ -62,13 +62,13 @@ internal SearchDirectoryArgs(string dir, int totalDirs, int completedDirs)
}
public class FileSearcher
{
- public event EventHandler<FileFoundArgs> OnFoundFile;
- internal event EventHandler<SearchDirectoryArgs> OnChangeDirectory
+ public event EventHandler<FileFoundArgs> FoundFile;
@mairaw
mairaw Sep 7, 2016 Collaborator

I think the noun should come first and then the verb. So it would be FileFound event and DirectoryChanged event.
Some examples: ControlRemoved, SystemColorsChanged, UserPreferenceChanging, etc.

@terrajobst might know all the rules since he drives the framework design discussions.

@BillWagner
BillWagner Sep 7, 2016 Collaborator

I looked, and didn't find any statement either way in the Framework Design Guidelines, but if there is a convention, I'll follow it.

@mairaw
mairaw Sep 7, 2016 Collaborator

That is just my observation on actual API names. I haven't looked at the guidelines.

@BillWagner
BillWagner Sep 7, 2016 Collaborator

Even if it's not written, but a de facto guideline, I'll make the change. Waiting for @terrajobst to weigh in.

@mairaw mairaw and 1 other commented on an outdated diff Sep 7, 2016
docs/csharp/events-overview.md
the event reports something that has happened. Use a present tense verb (for
-example, `OnClosing`) to report something that is about to happen. Often, using
+example, `Closing`) to report something that is about to happen. Often, using
@mairaw
mairaw Sep 7, 2016 Collaborator

Closing would be present participle no? And we also have some that are simple present that don't have cancellation such as Authenticate. Any recommendation on when to use one vs. the other?

@BillWagner
BillWagner Sep 7, 2016 Collaborator

On the present participle: I'd prefer not going into that much grammatical detail for developers. Would you agree?
On the guidance: I'll do a bit of research and add a paragraph.

@mairaw
mairaw Sep 7, 2016 Collaborator

Sounds good.

@BillWagner BillWagner add language about other scenarios beyond cancellation
6d5ab03
@qinezh
Collaborator
qinezh commented Sep 7, 2016

Open Publishing Build Service: The pull request content has been published and here are some sample preview links:

@BillWagner
Collaborator

There's one remaining open feedback item. I'll propose this:

Proposal:

Change event names that are verb phrases from VerbNoun (ChangedDirectory) to NounVerb (DirectoryChanged).

Remain silent on whether this is a standard or not.

Can I get upvotes @mairaw and @terrajobst ? Once that happens, I'll make that change and merge.

@terrajobst
Member

Change event names that are verb phrases from VerbNoun (ChangedDirectory) to NounVerb (DirectoryChanged).

👍 That's what the framework does.

@BillWagner BillWagner Update event names to NounVerb phrasing.
d3376ea
@mairaw
Collaborator
mairaw commented Sep 8, 2016

LGTM!

@qinezh
Collaborator
qinezh commented Sep 8, 2016

Open Publishing Build Service: The pull request content has been published and here are some sample preview links:

@BillWagner BillWagner merged commit 59cb2f6 into dotnet:master Sep 8, 2016

3 checks passed

OpenPublishing.Build Open publishing build succeeded.
Details
OrcaBot [.NET Core - Nix] Samples built successfully on Ubuntu (x64).
Details
OrcaBot [.NET Core - Win] Samples built successfully on Windows (x64).
Details
@BillWagner BillWagner deleted the BillWagner:update-events-article branch Sep 8, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment