Coding style

Write for the next person who needs to understand or change the code

Prose

• use direct, human-readable wording
• avoid em dashes
• do not add a period to the final sentence of a paragraph, list item, summary, parameter, return, or exception description
• prefer concrete behavior over marketing or filler text
• explain why a constraint exists when the reason is not obvious
• keep comments that explain intent, compatibility, or a non-obvious constraint; do not narrate the next statement

C# API documentation

Every public method must have XML documentation. Document public types and data members when their meaning is not self-evident

Public methods must include

• <summary> with the operation and its intent
• <param> for every parameter
• <returns> for every non-void result, including Task and Task<T>
• <exception> for every exception callers are expected to handle

This illustrative interface shows the documentation format; it is not a launcher contract

using System.IO;
using Hyprism.Core.Models;

public interface IProfileReader
{
    /// <summary>
    /// Loads the selected profile from persistent storage
    /// </summary>
    /// <param name="profileId">Stable identifier of the profile to load</param>
    /// <returns>The profile when it exists, otherwise <see langword="null"/></returns>
    /// <exception cref="IOException">Thrown when the profile file cannot be read</exception>
    public Profile? LoadProfile(string profileId);
}

Use <inheritdoc/> on an implementation only when the interface documents the complete contract

Structure

• keep UI-independent behavior in Hyprism.Core
• keep Avalonia resources and presentation state in Hyprism.Desktop
• depend on interfaces at host boundaries
• use async I/O and pass cancellation tokens through network or long-running work
• keep presentation-specific dependencies out of Core
• use [GeneratedRegex] for constant patterns and keep only genuinely dynamic regular expressions at runtime
• cache reusable JsonSerializerOptions instead of creating them at each serialization call
• prefer collection expressions and System.Threading.Lock when the target framework supports them
• add a using directive instead of repeating an unambiguous framework namespace in member bodies

Documentation changes follow the audience, example, and screenshot rules in AGENTS.md