Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
125 commits
Select commit Hold shift + click to select a range
163ed96
Initial work on adding remaining animations
bijington Jun 11, 2023
ed99dee
Added FlipVertical
bijington Jun 24, 2023
2560b69
Consistent behaviour when dealing with null
bijington Jun 24, 2023
40723e4
Added samples for the new types of animation
bijington Jun 24, 2023
3e18d3a
Merge branch 'main' into feature/add-animations
bijington Aug 3, 2023
815b4fc
Merge branch 'main' into feature/add-animations
TheCodeTraveler Aug 9, 2023
3306205
Merge branch 'main' into feature/add-animations
TheCodeTraveler Aug 14, 2023
ec6a24a
Merge branch 'main' into feature/add-animations
VladislavAntonyuk Aug 23, 2023
1e12715
Merge branch 'main' into feature/add-animations
TheCodeTraveler Aug 27, 2023
fa62c5f
Merge branch 'main' into feature/add-animations
bijington Sep 4, 2023
2ffb89a
Fix some unit tests
bijington Sep 4, 2023
1e1bd6b
Merge branch 'main' into feature/add-animations
bijington Nov 8, 2023
4ccb3b8
Merge branch 'main' into feature/add-animations
bijington Feb 20, 2024
6590859
Merge branch 'main' into feature/add-animations
TheCodeTraveler Mar 26, 2024
4a837eb
Update src/CommunityToolkit.Maui/Animations/ScaleAnimation.shared.cs
TheCodeTraveler Dec 10, 2024
2802346
Merge branch 'main' into feature/add-animations
TheCodeTraveler Nov 13, 2026
dddd59e
Fix mock ticker so one Fire loop drives all animation ticks
TheCodeTraveler Nov 13, 2026
4b3c8ac
Move the new animations to [BindableProperty] and return views to the…
TheCodeTraveler Nov 13, 2026
48744eb
Make FadeAnimation finish within its Length
TheCodeTraveler Nov 13, 2026
3ee8629
Add unit tests for every animation in the PR
TheCodeTraveler Nov 13, 2026
fc517a4
Return views on cancel, add a keyframe animation helper, and make the…
TheCodeTraveler Nov 13, 2026
88c704a
Add TadaAnimation and HeartbeatAnimation
TheCodeTraveler Nov 13, 2026
bfec962
Add RubberBandAnimation and BounceAnimation
TheCodeTraveler Nov 13, 2026
622cdde
Add SwingAnimation and WobbleAnimation
TheCodeTraveler Nov 13, 2026
aad8225
Share the keyframe test helpers across the attention seekers
TheCodeTraveler Nov 13, 2026
0793f18
Add cross-animation keyframe tests and sample demos for the new anima…
TheCodeTraveler Nov 13, 2026
a1d2c76
Address review of the new animations
TheCodeTraveler Nov 13, 2026
f98672a
Address review of the new animations
TheCodeTraveler Nov 13, 2026
782edd8
Run the To animations on the view's dispatcher
TheCodeTraveler Nov 13, 2026
250faa6
Add device tests for the animations
TheCodeTraveler Nov 13, 2026
0501a6f
Await the peak instead of polling it in the animation device tests
TheCodeTraveler Nov 13, 2026
9f7b317
Address review nits in the animation device tests
TheCodeTraveler Nov 13, 2026
d8da274
Name the dispatcher helper with the Async suffix
TheCodeTraveler Nov 13, 2026
b0203de
Add device tests for the attention seekers
TheCodeTraveler Nov 13, 2026
79513a3
Address the final review of the animations
TheCodeTraveler Nov 13, 2026
09d3b5b
Address the final review of the animations
TheCodeTraveler Nov 13, 2026
f7ff37d
Address the final review of the animations
TheCodeTraveler Nov 13, 2026
2519aa2
Validate FadeAnimation.Opacity like the other animations
TheCodeTraveler Nov 13, 2026
96f81e7
Treat the caller's own cancellation as normal in AnimationBehavior
TheCodeTraveler Nov 13, 2026
27e26dc
Correct the easing remarks of the attention seekers
TheCodeTraveler Nov 13, 2026
c607185
Explain the blocking wait in AnimationDispatchTests
TheCodeTraveler Nov 13, 2026
2f16128
Spin RotateAnimation a full turn from the view's own rotation
TheCodeTraveler Nov 13, 2026
c0d4d11
Return an interrupted To animation's view to rest
TheCodeTraveler Nov 13, 2026
270bac3
Add device tests for the interruption, cancellation and rotation changes
TheCodeTraveler Nov 13, 2026
e49c202
Demo the spin, token cancellation and CancelAnimations in the sample
TheCodeTraveler Nov 13, 2026
a4d9c1a
Keep an app's value set during CancelAnimations as the next run's ori…
TheCodeTraveler Nov 13, 2026
1ece1cc
Pin the mid-run animations-off fix and stop asserting an exact value …
TheCodeTraveler Nov 13, 2026
6731fa6
Pin the guard that lets an app's own To animation take over an interr…
TheCodeTraveler Nov 13, 2026
3099245
Keep the property tracker in step when an interrupted run returns the…
TheCodeTraveler Nov 13, 2026
79d9bb9
Pin the latest-run guard of the interrupted-run restore
TheCodeTraveler Nov 13, 2026
55b2c0e
Correct two comments in AnimateLegAsync
TheCodeTraveler Nov 13, 2026
79f84c8
Stop and start AnimationBehavior's animations in one UI-thread turn
TheCodeTraveler Nov 13, 2026
f0ceb54
Pin one-UI-turn takeover, the cancelled-token stop and the restored t…
TheCodeTraveler Nov 13, 2026
65423d2
Restore the no-BOM convention of two animation test files and name th…
TheCodeTraveler Nov 13, 2026
2c67ffd
Shorten the keep-ticking animations in two interruption tests
TheCodeTraveler Nov 14, 2026
5f6b8c3
Merge branch 'main' into feature/add-animations
TheCodeTraveler Nov 14, 2026
a9a29f2
Run the single-thread animation tests on an AsyncContext that is neve…
TheCodeTraveler Nov 14, 2026
e11339f
Stop the spin from AnimationBehaviorPage.OnDisappearing instead of ma…
TheCodeTraveler Nov 15, 2026
885a5c0
Give each animation device test class its own feature category again
TheCodeTraveler Nov 15, 2026
8e9bf85
Pin that AnimationBehavior swallows the OperationCanceledException of…
TheCodeTraveler Nov 15, 2026
5ac6e85
Fault the keyframe run's Task when restoring the view throws, instead…
TheCodeTraveler Nov 15, 2026
93d7a8f
Skip a keyframe run's start when its token was cancelled while the st…
TheCodeTraveler Nov 15, 2026
79320b4
Start the next animation from the value an app animation or write too…
TheCodeTraveler Nov 15, 2026
6109948
Abort a To animation's own tween only, so a stale cancellation cannot…
TheCodeTraveler Nov 15, 2026
17ba83f
Remove the stale PlaneProjection after a flip returns to 0 on Windows
TheCodeTraveler Nov 15, 2026
51e687a
Keep a running TranslateToAsync's target under Bounce, Shake and Wobb…
TheCodeTraveler Nov 15, 2026
6b3fd8c
Stop a running attention seeker when a To animation starts on a prope…
TheCodeTraveler Nov 15, 2026
2c01a95
Restore the no-BOM convention of AnimationDispatchTests
TheCodeTraveler Nov 15, 2026
0321711
Drop two comments that restate what the code does
TheCodeTraveler Nov 15, 2026
d2cc208
Make the tracker handover test fail without the Count guard and word …
TheCodeTraveler Nov 15, 2026
344d5b9
Throw only during the restore in the tests whose restore throws, so a…
TheCodeTraveler Nov 15, 2026
5e2165c
Name the translation setter for what it serves and word the EndRun co…
TheCodeTraveler Nov 15, 2026
78abf81
Pin that a run starts its tween before it registers for the token
TheCodeTraveler Nov 15, 2026
66b2b9c
Pin that a cancelled seeker keeps a translation the app wrote after t…
TheCodeTraveler Nov 15, 2026
cc7c71e
Pin that a run's end removes only its own record
TheCodeTraveler Nov 15, 2026
36f47ae
Start the nested run from the continuation of an aborted To animation…
TheCodeTraveler Nov 15, 2026
a080acb
Merge branch 'main' into feature/add-animations
TheCodeTraveler Nov 16, 2026
3e03359
Clear only MAUI's stale PlaneProjection after a flip on Windows
TheCodeTraveler Nov 16, 2026
a7a014d
Keep writing Bounce's first-hop height through the pause at its peak
TheCodeTraveler Nov 16, 2026
801ea02
Abort the app's To animation before a To run takes its tracker id
TheCodeTraveler Nov 16, 2026
253f9d6
Leave a nested seeker's properties to the run whose start aborted it
TheCodeTraveler Nov 16, 2026
418dbe1
Record a seeker's run only after it creates its keyframes
TheCodeTraveler Nov 16, 2026
f2a6cf5
Wait for mid-run only while the view is short of its peak
TheCodeTraveler Nov 16, 2026
0dc5b32
Give the surviving Swing three run lengths in the nested-Swing anchor…
TheCodeTraveler Nov 16, 2026
717513e
Merge feature/add-animations into the Copilot review fixes
TheCodeTraveler Nov 16, 2026
53c8c7b
Shorten the runs two new animation tests wait out so they fit the tim…
TheCodeTraveler Nov 16, 2026
b55b631
Shorten the mid-turn Rotate test's turn so it fits the timeout on slo…
TheCodeTraveler Nov 16, 2026
69a8558
Pick an app value the interrupted run can't hold so its write is neve…
TheCodeTraveler Nov 17, 2026
f0e5409
Wait for the item's Expander inside its container in the Windows Coll…
TheCodeTraveler Nov 17, 2026
0e562fa
Say how the interrupted run detects the app's write in the To-animati…
TheCodeTraveler Nov 17, 2026
f229ddc
Pace the mock ticker's frames on a spinning Stopwatch so slow CI time…
TheCodeTraveler Nov 17, 2026
7899fdf
Merge branch 'main' into feature/add-animations
TheCodeTraveler Nov 17, 2026
0308d90
Document that setting exactly the reached value doesn't take over fro…
TheCodeTraveler Nov 17, 2026
6edda0d
Merge remote-tracking branch 'origin/feature/add-animations' into cop…
TheCodeTraveler Nov 17, 2026
dd9a424
Merge branch 'expander-1116' into copilot-1116
TheCodeTraveler Nov 17, 2026
4f5f8e7
Give a contract animation that a test cancels mid-run three times the…
TheCodeTraveler Nov 17, 2026
44bb28e
Drop the timer wake-up comment the spin-paced mock ticker made stale
TheCodeTraveler Nov 17, 2026
e1ef3d5
Merge branch 'ticker-1116' into copilot-1116
TheCodeTraveler Nov 17, 2026
090ae4d
Keep an app-supplied PlaneProjection through a flip that never turns …
TheCodeTraveler Nov 20, 2026
890ef17
Restore the right translation when another writer's write equals the …
TheCodeTraveler Nov 20, 2026
ea40bc7
Keep a seeker's offset visible under a TranslateToAsync that starts d…
TheCodeTraveler Nov 20, 2026
30ab460
Document that a TranslateToAsync started during a seeker also carries…
TheCodeTraveler Nov 20, 2026
1919770
Let an app's ScaleToAsync or RotateToAsync that starts during an atte…
TheCodeTraveler Nov 20, 2026
c275a75
Document that an app's ScaleToAsync or RotateToAsync that starts duri…
TheCodeTraveler Nov 20, 2026
67510c7
Pin that the app's ScaleToAsync or RotateToAsync takes over before th…
TheCodeTraveler Nov 20, 2026
ab28da4
Pin that a To animation of a property a seeker does not animate leave…
TheCodeTraveler Nov 20, 2026
25e9329
Merge branch 'main' into feature/add-animations
TheCodeTraveler Nov 20, 2026
8f83d21
Act mid-run in the animation device tests only in a turn that sees th…
TheCodeTraveler Nov 20, 2026
d990a0c
Keep the keyframe device tests meaningful when the UI thread stalls
TheCodeTraveler Nov 20, 2026
cd26956
Give Rotate a late first frame that leaves its only leg running
TheCodeTraveler Nov 20, 2026
dc9a4f5
Act mid-run only while the run's Task is still going
TheCodeTraveler Nov 20, 2026
87123d5
Give the off-UI-thread mid-run actions a 10 s run
TheCodeTraveler Nov 20, 2026
d7397e7
Prove a missed bounce attempt by ticker time and measure hops against…
TheCodeTraveler Nov 20, 2026
fff75e7
Keep every assertion of a stalled attempt that acted, and surface a m…
TheCodeTraveler Nov 20, 2026
02a71a5
Merge branch 'feature/add-animations' (main merged in) into the stall…
TheCodeTraveler Nov 20, 2026
2219e1b
Describe MAUI's animations in plain words in the animation comments
TheCodeTraveler Nov 20, 2026
580eb3b
Name the animation tests and locals in plain words
TheCodeTraveler Nov 20, 2026
ea71f0b
Name the round-trip animation helpers after what they do
TheCodeTraveler Nov 20, 2026
2885483
Add naming conventions to the contributor guide and agent instructions
TheCodeTraveler Nov 20, 2026
9dae26c
Name the animation members by the naming conventions
TheCodeTraveler Nov 20, 2026
a87b4ca
Align the guides' older examples with the naming conventions
TheCodeTraveler Nov 20, 2026
e200177
Merge branch 'main' into feature/add-animations
TheCodeTraveler Nov 20, 2026
cf7b6a2
Merge branch 'main' into feature/add-animations
TheCodeTraveler Nov 21, 2026
f1886bc
Run the animation device tests below Android API 26 too, with the sha…
TheCodeTraveler Nov 21, 2026
1586f2f
Merge branch 'main' into feature/add-animations
TheCodeTraveler Nov 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 29 additions & 3 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ This document provides guidelines for using GitHub Copilot to contribute to the
* Use file-scoped namespaces to reduce code verbosity.
* Write comments only to explain **why** (a non-intuitive decision, a platform quirk or workaround, code that looks out of scope); never to explain **what** the code does. Use descriptive names instead.
* Avoid using the **!** null forgiving operator.
* Follow naming conventions for enums and property names.
* Follow the Naming Conventions section below, and the naming guidelines for enums and property names.
* Code that reads or formats with **CurrentCulture** or takes a **CultureInfo** must be tested in Turkish (tr-TR, az-Latn-AZ) and the other notorious cultures; see `.github/instructions/culture.instructions.md`.
* Handler lifecycle: confirmed in .NET MAUI 11.0.10, `CreatePlatformView` runs once per handler in a real app; do not ask for guards against a second call; see `.github/instructions/handler-lifecycle.instructions.md`.

Expand All @@ -71,9 +71,35 @@ StyleCop rules SA1201, SA1202, SA1204, SA1214, and SA1215 are reported as **buil
### Enums
* Always use `Unknown` at index 0 for return types that may have a value that is not known
* Always use `Default` at index 0 for option types that can use the system default option
* Follow naming guidelines for tense... `SensorSpeed` not `SensorSpeeds`
* Follow naming guidelines for number (singular, not plural)... `SensorSpeed` not `SensorSpeeds`
* Assign values (0,1,2,3) for all enums, if not marked with a `Flags` attribute. This is to ensure that the enum can be serialized and deserialized correctly across platforms.

### Naming Conventions

Names tell the story of the code, so it needs no comment that says *what* it does. Apply these rules to code you add or change. Don't rename code you aren't otherwise changing.

* **Methods, `Action`s and `Func`s are verbs** that describe both the action they do and the result they return.
* `GetOrCreate(view, property)`, not `For(view, property)`
* `StartAnimationAndGetOriginalValue(currentValue)`, not `Start(currentValue)`
* A method that handles an event keeps the .NET `On<EventName>` form, such as `OnRegexPropertyChanged`. A callback passed as a parameter is still a verb: `handleFrame`, not `onFrame`.
* **Past tense is only for events.** A method that records that something happened still starts with a verb.
* `RecordHandOverToApp(animationId)`, not `HandedOverToApp(animationId)`
* **A method that returns a `bool` to say whether it succeeded follows the [Try-Parse pattern](https://learn.microsoft.com/dotnet/standard/design-guidelines/exceptions-and-performance#try-parse-pattern).**
* Start its name with `Try` and return `true` on success.
* Return any other result through an `out` parameter. The parameter is `null` when the method returns `false`, and `[NotNullWhen(true)]` tells the compiler it isn't `null` when the method returns `true`.
* A method that only answers a question, such as `IsLatest(animationId)`, is not a `Try` method.

```csharp
public bool TryGetTracker(VisualElement view, [NotNullWhen(true)] out AnimatedPropertyTracker? tracker)
```

* **Properties, fields and local variables are nouns.** A `bool` is a question.
* `public bool DidAnimationComplete { get; private set; }`
* `var wasTranslationInterrupted = ...`, not `var translationWasInterrupted = ...`
* A `Task` or `TaskCompletionSource` ends with what it is: `peakReachedTask` and `animationEndedSource`, not `peakReached` and `animationEnded`.
* **Events are past-tense verbs** that describe what happened.
* `MediaFailed`, `MediaEnded`

### Property Names
* Include units only if one of the platforms includes it in their implementation. For instance HeadingMagneticNorth implies degrees on all platforms, but PressureInHectopascals is needed since platforms don't provide a consistent API for this.

Expand Down Expand Up @@ -102,7 +128,7 @@ if (canRetry)

// Prefer - a comment that explains why
// AVPlayerItem reports an indefinite duration until its asset has loaded, so wait for ReadyToPlay before reading it
await readyToPlay.Task.WaitAsync(token);
await readyToPlaySource.Task.WaitAsync(token);
```

### Pattern matching
Expand Down
53 changes: 31 additions & 22 deletions .github/instructions/codestyle.instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,39 @@ This guide provides a set of best practices and coding standards for writing C#

// Good: the comment explains why
// AVPlayerItem reports an indefinite duration until its asset has loaded, so wait for ReadyToPlay before reading it
await readyToPlay.Task.WaitAsync(token);
await readyToPlaySource.Task.WaitAsync(token);

// Avoid: the comment repeats the code
// Check whether the user can retry
if (attempts < 3 && !isCancelled)
```

## Naming Conventions:

Names tell the story of the code, so it needs no comment that says *what* it does. Apply these rules to code you add or change. Don't rename code you aren't otherwise changing.

- **Methods, `Action`s and `Func`s are verbs** that describe both the action they do and the result they return.
- `GetOrCreate(view, property)`, not `For(view, property)`
- `StartAnimationAndGetOriginalValue(currentValue)`, not `Start(currentValue)`
- A method that handles an event keeps the .NET `On<EventName>` form, such as `OnRegexPropertyChanged`. A callback passed as a parameter is still a verb: `handleFrame`, not `onFrame`.
- **Past tense is only for events.** A method that records that something happened still starts with a verb.
- `RecordHandOverToApp(animationId)`, not `HandedOverToApp(animationId)`
- **A method that returns a `bool` to say whether it succeeded follows the [Try-Parse pattern](https://learn.microsoft.com/dotnet/standard/design-guidelines/exceptions-and-performance#try-parse-pattern).**
- Start its name with `Try` and return `true` on success.
- Return any other result through an `out` parameter. The parameter is `null` when the method returns `false`, and `[NotNullWhen(true)]` tells the compiler it isn't `null` when the method returns `true`.
- A method that only answers a question, such as `IsLatest(animationId)`, is not a `Try` method.

```csharp
public bool TryGetTracker(VisualElement view, [NotNullWhen(true)] out AnimatedPropertyTracker? tracker)
```

- **Properties, fields and local variables are nouns.** A `bool` is a question.
- `public bool DidAnimationComplete { get; private set; }`
- `var wasTranslationInterrupted = ...`, not `var translationWasInterrupted = ...`
- A `Task` or `TaskCompletionSource` ends with what it is: `peakReachedTask` and `animationEndedSource`, not `peakReached` and `animationEnded`.
- **Events are past-tense verbs** that describe what happened.
- `MediaFailed`, `MediaEnded`

## Type Definitions:
- Prefer records for data types:
```csharp
Expand Down Expand Up @@ -219,12 +245,10 @@ This guide provides a set of best practices and coding standards for writing C#
_ => ImageSource.FromResource(value, Application.Current?.GetType().Assembly)
};

// Method never returns null
[return: NotNull]
public static string EnsureNotNull(string? input) =>
input ?? string.Empty;

// Parameter must not be null when method returns true
public static bool TryParse(string? input, [NotNullWhen(true)] out string? result)
{
result = null;
Expand Down Expand Up @@ -252,14 +276,11 @@ This guide provides a set of best practices and coding standards for writing C#
```csharp
public interface IOrderRepository
{
// Explicitly shows that null is a valid return value
Task<Order?> FindByIdAsync(OrderId id, CancellationToken ct = default);

// Method will never return null
[return: NotNull]
Task<IReadOnlyList<Order>> GetAllAsync(CancellationToken ct = default);

// Parameter cannot be null
Task SaveAsync([NotNull] Order order, CancellationToken ct = default);
}
```
Expand Down Expand Up @@ -349,8 +370,8 @@ This guide provides a set of best practices and coding standards for writing C#

// Good: Using Try methods in LINQ with pattern matching
var validNumbers = strings
.Select(s => (Success: int.TryParse(s, out var num), Value: num))
.Where(x => x.Success)
.Select(s => (WasParsed: int.TryParse(s, out var num), Value: num))
.Where(x => x.WasParsed)
.Select(x => x.Value);
```

Expand Down Expand Up @@ -435,11 +456,11 @@ This guide provides a set of best practices and coding standards for writing C#
- Use TaskCompletionSource correctly:
```csharp
// Good: Using RunContinuationsAsynchronously
private readonly TaskCompletionSource<Order> _tcs =
private readonly TaskCompletionSource<Order> orderSource =
new(TaskCreationOptions.RunContinuationsAsynchronously);

// Avoid: Default TaskCompletionSource can cause deadlocks
private readonly TaskCompletionSource<Order> _tcs = new();
private readonly TaskCompletionSource<Order> orderSource = new();
```
- Always dispose CancellationTokenSources:
```csharp
Expand Down Expand Up @@ -630,15 +651,3 @@ Within a class, struct, or interface, elements should be positioned in the follo
11. Records
12. Structs
13. Classes

### Try Pattern

When a method name begins with `Try` and returns a variable, ensure it adheres to the Try Pattern.

Here Key Components of the Try Pattern:
1. Method Name: Begins with Try (e.g., TryParse, TryGetValue).
2. Return Type: bool (indicating success or failure).
3. Out Parameter: An out parameter to return the result if successful.
4. Null Analysis Attribute: [NotNullWhen(true)] (or [MaybeNullWhen(false)]) informs the compiler that if the method returns true, the out parameter is guaranteed to be non-null.

This pattern allows for high-performance retrieval or parsing without throwing exceptions for expected failures. It also allows cleaner call sites by eliminating the need for null-checking the output variable within the if block, as seen in Dictionary<TKey, TValue>.TryGetValue.
47 changes: 34 additions & 13 deletions .github/prompts/dotnet/codestyle.prompt.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,32 @@
# Coding Style Guide
This guide provides a set of best practices and coding standards for writing C# code with GitHub Copilot. It covers various aspects of C# programming, including naming conventions, code structure, control flow, nullability, safe operations, asynchronous programming, and symbol references.

## Naming Conventions:

Names tell the story of the code, so it needs no comment that says *what* it does. Apply these rules to code you add or change. Don't rename code you aren't otherwise changing.

- **Methods, `Action`s and `Func`s are verbs** that describe both the action they do and the result they return.
- `GetOrCreate(view, property)`, not `For(view, property)`
- `StartAnimationAndGetOriginalValue(currentValue)`, not `Start(currentValue)`
- A method that handles an event keeps the .NET `On<EventName>` form, such as `OnRegexPropertyChanged`. A callback passed as a parameter is still a verb: `handleFrame`, not `onFrame`.
- **Past tense is only for events.** A method that records that something happened still starts with a verb.
- `RecordHandOverToApp(animationId)`, not `HandedOverToApp(animationId)`
- **A method that returns a `bool` to say whether it succeeded follows the [Try-Parse pattern](https://learn.microsoft.com/dotnet/standard/design-guidelines/exceptions-and-performance#try-parse-pattern).**
- Start its name with `Try` and return `true` on success.
- Return any other result through an `out` parameter. The parameter is `null` when the method returns `false`, and `[NotNullWhen(true)]` tells the compiler it isn't `null` when the method returns `true`.
- A method that only answers a question, such as `IsLatest(animationId)`, is not a `Try` method.

```csharp
public bool TryGetTracker(VisualElement view, [NotNullWhen(true)] out AnimatedPropertyTracker? tracker)
```

- **Properties, fields and local variables are nouns.** A `bool` is a question.
- `public bool DidAnimationComplete { get; private set; }`
- `var wasTranslationInterrupted = ...`, not `var translationWasInterrupted = ...`
- A `Task` or `TaskCompletionSource` ends with what it is: `peakReachedTask` and `animationEndedSource`, not `peakReached` and `animationEnded`.
- **Events are past-tense verbs** that describe what happened.
- `MediaFailed`, `MediaEnded`

## Type Definitions:
- Prefer records for data types:
```csharp
Expand Down Expand Up @@ -33,10 +59,10 @@ This guide provides a set of best practices and coding standards for writing C#

- Prefer range indexers over LINQ:
```csharp
// Good: Using range indexers with clear comments
var lastItem = items[^1]; // ^1 means "1 from the end"
var firstThree = items[..3]; // ..3 means "take first 3 items"
var slice = items[2..5]; // take items from index 2 to 4 (5 exclusive)
// Good: Using range indexers
var lastItem = items[^1];
var firstThree = items[..3];
var slice = items[2..5];

// Avoid: Using LINQ when range indexers are clearer
var lastItem = items.LastOrDefault();
Expand Down Expand Up @@ -209,12 +235,10 @@ This guide provides a set of best practices and coding standards for writing C#
_ => ImageSource.FromResource(value, Application.Current?.GetType().Assembly)
};

// Method never returns null
[return: NotNull]
public static string EnsureNotNull(string? input) =>
input ?? string.Empty;

// Parameter must not be null when method returns true
public static bool TryParse(string? input, [NotNullWhen(true)] out string? result)
{
result = null;
Expand Down Expand Up @@ -254,14 +278,11 @@ This guide provides a set of best practices and coding standards for writing C#
```csharp
public interface IOrderRepository
{
// Explicitly shows that null is a valid return value
Task<Order?> FindByIdAsync(OrderId id, CancellationToken ct = default);

// Method will never return null
[return: NotNull]
Task<IReadOnlyList<Order>> GetAllAsync(CancellationToken ct = default);

// Parameter cannot be null
Task SaveAsync([NotNull] Order order, CancellationToken ct = default);
}
```
Expand Down Expand Up @@ -316,8 +337,8 @@ This guide provides a set of best practices and coding standards for writing C#

// Good: Using Try methods in LINQ with pattern matching
var validNumbers = strings
.Select(s => (Success: int.TryParse(s, out var num), Value: num))
.Where(x => x.Success)
.Select(s => (WasParsed: int.TryParse(s, out var num), Value: num))
.Where(x => x.WasParsed)
.Select(x => x.Value);
```

Expand Down Expand Up @@ -402,11 +423,11 @@ This guide provides a set of best practices and coding standards for writing C#
- Use TaskCompletionSource correctly:
```csharp
// Good: Using RunContinuationsAsynchronously
private readonly TaskCompletionSource<Order> _tcs =
private readonly TaskCompletionSource<Order> orderSource =
new(TaskCreationOptions.RunContinuationsAsynchronously);

// Avoid: Default TaskCompletionSource can cause deadlocks
private readonly TaskCompletionSource<Order> _tcs = new();
private readonly TaskCompletionSource<Order> orderSource = new();
```
- Always dispose CancellationTokenSources:
```csharp
Expand Down
7 changes: 7 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,13 @@ Every change to the four packages must keep them fully trim-safe and NativeAOT-s

Interim, until CommunityToolkit/Maui#3438 (nightly bump bot) lands: when you review or change a device test workflow, check its Android API level, iOS runtime, Xcode and Windows runner against the newest GA releases and recommend a bump. The list is in [.github/instructions/trimming-aot.instructions.md](.github/instructions/trimming-aot.instructions.md#newest-os-versions-interim).

## Naming

* Methods, `Action`s and `Func`s are verbs that say the action and the result: `GetOrCreate`, not `For`. Past tense is only for events. A method that handles an event keeps the .NET `On<EventName>` form (`OnRegexPropertyChanged`); a callback parameter is a verb (`handleFrame`).
* A method that returns a `bool` to say whether it succeeded starts with `Try` and returns any other result through a `[NotNullWhen(true)] out` parameter. A method that only answers a question, such as `IsLatest`, is not a `Try` method.
* Properties, fields and locals are nouns; a `bool` is a question (`DidAnimationComplete`). A `Task` ends with `Task` and a `TaskCompletionSource` with `Source` (`peakReachedTask`, `animationEndedSource`).
* Apply this to code you add or change. Don't rename code you aren't otherwise changing. Full rules: [CONTRIBUTING.md](CONTRIBUTING.md#naming-conventions).

## Instructions

* [.github/copilot-instructions.md](.github/copilot-instructions.md): general rules for contributors and agents
Expand Down
30 changes: 28 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,7 @@ if (canRetry)

// Prefer - a comment that explains why
// AVPlayerItem reports an indefinite duration until its asset has loaded, so wait for ReadyToPlay before reading it
await readyToPlay.Task.WaitAsync(token);
await readyToPlaySource.Task.WaitAsync(token);
var duration = playerItem.Duration;
```

Expand All @@ -209,9 +209,35 @@ var duration = playerItem.Duration;

* Always use `Unknown` at index 0 for return types that may have a value that is not known
* Always use `Default` at index 0 for option types that can use the system default option
* Follow naming guidelines for tense... `SensorSpeed` not `SensorSpeeds`
* Follow naming guidelines for number (singular, not plural)... `SensorSpeed` not `SensorSpeeds`
* Assign values (0,1,2,3) for all enums

### Naming Conventions

Names tell the story of the code, so it needs no comment that says *what* it does. Apply these rules to code you add or change. Don't rename code you aren't otherwise changing.

* **Methods, `Action`s and `Func`s are verbs** that describe both the action they do and the result they return.
* `GetOrCreate(view, property)`, not `For(view, property)`
* `StartAnimationAndGetOriginalValue(currentValue)`, not `Start(currentValue)`
* A method that handles an event keeps the .NET `On<EventName>` form, such as `OnRegexPropertyChanged`. A callback passed as a parameter is still a verb: `handleFrame`, not `onFrame`.
* **Past tense is only for events.** A method that records that something happened still starts with a verb.
* `RecordHandOverToApp(animationId)`, not `HandedOverToApp(animationId)`
* **A method that returns a `bool` to say whether it succeeded follows the [Try-Parse pattern](https://learn.microsoft.com/dotnet/standard/design-guidelines/exceptions-and-performance#try-parse-pattern).**
* Start its name with `Try` and return `true` on success.
* Return any other result through an `out` parameter. The parameter is `null` when the method returns `false`, and `[NotNullWhen(true)]` tells the compiler it isn't `null` when the method returns `true`.
* A method that only answers a question, such as `IsLatest(animationId)`, is not a `Try` method.

```csharp
public bool TryGetTracker(VisualElement view, [NotNullWhen(true)] out AnimatedPropertyTracker? tracker)
```

* **Properties, fields and local variables are nouns.** A `bool` is a question.
* `public bool DidAnimationComplete { get; private set; }`
* `var wasTranslationInterrupted = ...`, not `var translationWasInterrupted = ...`
* A `Task` or `TaskCompletionSource` ends with what it is: `peakReachedTask` and `animationEndedSource`, not `peakReached` and `animationEnded`.
* **Events are past-tense verbs** that describe what happened.
* `MediaFailed`, `MediaEnded`

### Property Names

* Include units only if one of the platforms includes it in their implementation. For instance HeadingMagneticNorth implies degrees on all platforms, but PressureInHectopascals is needed since platforms don't provide a consistent API for this.
Expand Down
Loading
Loading