Skip to content

AGENTS.md

Latest commit

 

History

History
146 lines (109 loc) · 7.56 KB

AGENTS.md

File metadata and controls

146 lines (109 loc) · 7.56 KB

Tomlyn Code Contribution Instructions

Overview

  • In the readme.md file, you will find general information about the Tomlyn project.
  • In the doc/readme.md file you will find the user guide documentation for the Tomlyn library.

Project Structure

  • In the src/Tomlyn folder you will find the code for the main Tomlyn library.
  • In the src/Tomlyn.Tests folder you will find the unit tests for the library.
  • In the src/Tomlyn.SourceGeneration folder you will find the AOT-friendly source generator for TOML model mapping.
  • In the src/Tomlyn.Signed folder you will find the strong-named signed version of the library.
  • In the src/Tomlyn.AotTests folder you will find AOT compatibility tests.
  • In the src/Tomlyn.Benchmarks folder you will find performance benchmarks.
  • In the ext/toml-test folder you will find the external TOML test suite used for standard compliance testing.

Building and Testing

  • To build the project, navigate to the src directory and run dotnet build -c Release.
  • To run the unit tests, navigate to the src directory and run dotnet test -c Release.
  • Ensure that all tests pass successfully before submitting any changes.
  • Ensure that user guide documentation (doc/readme.md) and top-level readme are updated to reflect any changes made to the library.

General Coding Instructions

  • Follow the coding style and conventions used in the existing code base.
  • Write clear and concise inline comments to explain the purpose and functionality of your code. This is about the "why" more than the "what".
  • All public APIs must have XML documentation comments to avoid CS1591 warnings.
  • Ensure that your code is well-structured and modular to facilitate maintenance and future enhancements.
  • Adhere to best practices for error handling and input validation.
  • Write unit tests for any new functionality you add to ensure code quality and reliability.
    • When fixing a bug, add a unit test that reproduces the bug before implementing the fix.
  • Use meaningful variable and method names that accurately reflect their purpose.
  • Avoid code duplication by reusing existing methods and classes whenever possible.

C# Coding Conventions

Naming Conventions

  • Use PascalCase for public members, types, and namespaces.
  • Use camelCase for local variables and parameters.
  • Use _camelCase (with underscore prefix) for private fields.
  • Prefix interfaces with I (e.g., IMyInterface).
  • Use descriptive names; avoid abbreviations unless widely understood (e.g., Id, Url).

Code Style

  • Use file-scoped namespaces (namespace Tomlyn;) unless the file requires multiple namespaces.
  • Use var when the type is obvious from the right-hand side; otherwise, use explicit types.
  • Prefer expression-bodied members for single-line implementations.
  • Use pattern matching and switch expressions where they improve readability.
  • Place using directives outside the namespace, sorted alphabetically with System namespaces first.

Nullable Reference Types

  • This project uses nullable reference types. Respect nullability annotations.
  • Never suppress nullable warnings (#pragma warning disable) without a comment explaining why.
  • Use ArgumentNullException.ThrowIfNull() for null checks on parameters.
  • Prefer is null and is not null over == null and != null.

Error Handling

  • Throw ArgumentException or ArgumentNullException for invalid arguments.
  • Use specific exception types rather than generic Exception.
  • Include meaningful error messages that help diagnose the issue.
  • Document exceptions in XML comments using <exception cref="...">.

Async/Await

  • Suffix async methods with Async (e.g., LoadDataAsync).
  • Use ConfigureAwait(false) in library code unless context capture is required.
  • Prefer ValueTask<T> over Task<T> for hot paths that often complete synchronously.
  • Never use async void except for event handlers.

Performance Considerations

  • Ensure that the code is optimized for performance without sacrificing readability.
  • Ensure that the code minimizes GC allocations where possible.
    • Use Span<T>/ReadOnlySpan<T> where appropriate to reduce memory allocations.
    • Use stackalloc for small, fixed-size buffers in performance-critical paths.
    • Prefer StringBuilder for string concatenation in loops.
    • Use ArrayPool<T> for temporary arrays that would otherwise cause allocations.
  • Ensure generated code is AOT-compatible and trimmer-friendly.
    • Avoid reflection where possible; prefer source generators.
    • Use [DynamicallyAccessedMembers] attributes when reflection is necessary.
  • Use sealed on classes that are not designed for inheritance to enable devirtualization.
  • Prefer ReadOnlySpan<char> over string for parsing and substring operations.

Source Generator Guidelines

  • The TomlModelAttribute only needs to be applied to the root type; nested model types are discovered transitively.
  • Ensure generated code is AOT-compatible and trimmer-friendly.

Testing Guidelines

Test Organization

  • Name test classes as {ClassName}Tests (e.g., ParserTests).
  • Name test methods descriptively: {MethodName}_{Scenario}_{ExpectedResult} or use plain English.
  • Group related tests using #region or nested classes if the test file is large.

Test Quality

  • Each test should verify one specific behavior (single assertion concept).
  • Use the Arrange-Act-Assert (AAA) pattern.
  • Include edge cases: null inputs, empty collections, boundary values, and error conditions.
  • Avoid test interdependencies; each test must be able to run in isolation.

Test Coverage

  • Aim for high coverage of public APIs and critical code paths.
  • Prioritize testing complex logic, error handling, and edge cases over trivial code.
  • When fixing a bug, first write a test that reproduces the bug, then fix it.

API Design Guidelines

  • Follow .NET API design guidelines for consistency with the ecosystem.
  • Don't over engineer APIs; keep them simple and focused.
  • Don't introduce unnecessary interface abstractions; prefer concrete types unless specific extensibility is required that is preferred through an interface.
  • Use immutable types where possible to enhance thread safety and predictability.
  • Allow mutable types when necessary for performance or usability.
  • Make APIs hard to misuse: validate inputs early, use strong types.
  • Prefer method overloads over optional parameters for binary compatibility.
  • Use params ReadOnlySpan<T> for variadic methods (C# 13+) when targeting modern runtimes.
  • Consider adding Try* pattern methods (returning bool) alongside throwing versions.
  • Mark obsolete APIs with [Obsolete("message", error: false)] before removal.

Git Commit Instructions

  • Write a concise and descriptive commit message that summarizes the changes made.
  • Start the commit message with a verb in imperative mood (e.g., "Add", "Fix", "Update", "Remove").
  • Keep the first line under 72 characters; add details in the body if needed.
  • Create a commit for each logical change or feature added to facilitate easier code review and tracking of changes.
  • Reference related issues in commit messages when applicable (e.g., "Fix #123").

Pre-Submission Checklist

Before submitting changes, verify:

  • Code builds without errors or warnings (dotnet build -c Release).
  • All tests pass (dotnet test -c Release).
  • New public APIs have XML documentation comments.
  • Changes are covered by unit tests.
  • No unintended files are included in the commit. But don't remove code that was changed locally but is not part of your intended changes.
  • Documentation is updated if behavior changes.
⚡