QuikGraph Documentation

Provider (Strategy) Pattern

Used heavily for defining contracts. Use specific suffixes to clarify intent:

• Provider suffix: Use when the contract primarily allows the caller to get something.
• Reader and Writer interfaces: If a contract allows both getting and setting, split it into two interfaces to clarify intent.

Creational Patterns

Use patterns when object creation involves significant logic:

• Factory Pattern: When logic doesn't fit in a constructor.
• Create semantics: For items built in a single step.
• Build semantics: For items built up over multiple steps.

Null Object Pattern

When providing an implementation of an interface that does nothing, use the Null Object Pattern instead of returning null.

// Decomposing a Provider into Reader/Writer
public interface ICacheReader
{
    bool TryGetObject(string key, out object value);
}

public interface ICacheWriter
{
    void RemoveObjects(string keys);
    void RemoveObject(string key);
    void SetObject(string key, object obj);
    void InsertObject(string key, object value, DateTime absoluteExpiration, TimeSpan slidingExpiration);
}

// Null Object Pattern
public interface ISomething
{
    DateTime GetDateTime(string parameter);
}

public class NullSomething : ISomething
{
    public DateTime GetDateTime(string parameter) => default(DateTime);
}

Follow these general guidelines to maintain code quality within the project:

• Explicit Visibility: Always use explicit scope/visibility modifiers (e.g., public, private). Avoid relying on default access levels.
• File Structure: Aim for one class per file, except for inner classes.
• String Handling: Use string.Empty instead of empty quotes ("") where possible.
• Method Length: Keep methods short (ideally 20-30 lines). Refactor into smaller, well-named methods if they exceed this.
• Local Functions: Limit the use of captured variables from the enclosing method and keep local functions short.
• Fail Fast / Exit Fast: Perform validation and early returns/exceptions at the top of the method to avoid deep nesting or unnecessary else clauses.
• Avoid dynamic: Avoid the dynamic keyword, especially in performance-critical code, due to the high cost of dynamic dispatch.
• KeyValuePair Naming: If you must pass values via KeyValuePair<TKey, TValue>, use a naming format like {keyName}And{valueName} (e.g., studentIdAndName).
• Anonymous Type Formatting: Use explicit property names on anonymous types and place each property on a separate line.

// Fail Fast pattern
public void SomeMethod(ISomething something)
{
    if (something is null)
        throw new ArgumentNullException(nameof(something));

    var things = _somethingElse.GetThoseThings();
    // ... logic continues without an else block
}

// Anonymous type formatting
var anonymousObj = new
{
    Property1 = sourceA.Property1,
    Property2 = sourceB.Property2
};

When writing LINQ queries in QuikGraph, follow these patterns to ensure readability and performance:

• Prefer Method Syntax: Use method syntax (e.g., .Where(), .Select()) over query syntax.
• Meaningful Naming: Use descriptive names for query variables (e.g., tolkienBooks instead of list).
• Anonymous Type Aliasing: Use aliases in anonymous types to ensure property names follow Pascal casing.
• Resolve Ambiguity: Rename properties in anonymous types if the resulting names (like Name or Id) are ambiguous.
• Filter Early: Place Where clauses before other operations like OrderBy or Select to ensure subsequent operations work on a reduced dataset.
• Explicit Typing: Prefer explicit typing for query and range variables unless the expression is excessively long.

// Filter early and use meaningful names
var tolkienBooks = books.Where(x => x.Author == "Tolkien")
                        .OrderBy(x => x.PublicationYear)
                        .Select(x => x.Name);

// Use aliases to avoid ambiguity in anonymous types
var booksInfo = books.Join(
    authors,
    book => book.Author,
    author => author.Name,
    (book, author) => new
    {
        BookName = book.Name,
        AuthorId = author.Id
    });

Use clear, descriptive names for all identifiers. Avoid double negatives in method names (e.g., avoid IsNotConnected if the method actually performs a connection attempt; use TryConnect instead).

Generic Types:

• Single generic type: Use T (e.g., ISomething<T>) unless a more precise name like TEdge is appropriate.
• Multiple generic types: Use a capital T followed by a descriptive name (e.g., IService<TRequest, TResponse>).

Suffixes and Enumerations:

• Custom attributes must use the Attribute suffix.
• Custom exceptions must use the Exception suffix.
• Enumerations should be singular (e.g., FileMode) unless they represent bit flags using the [Flags] attribute (e.g., FileAttributes).

// Bad: Double negative and misleading behavior
private static bool IsNotConnected(SocketWrapper socket, string serverName) { ... }

// Good: Clear intent
private static bool TryConnect(SocketWrapper socket, string serverName) { ... }

// Generics
public interface ISomething<T>
public interface IService<TRequest, TResponse>