This project targets modern development environments with wide displays. The traditional 80-character line limit is unnecessarily restrictive and results in excessive line wrapping and vertical scrolling. To balance readability with modern screen real estate, we adopt a maximum line length of 160 characters. This allows for more natural formatting of fluent APIs, LINQ queries, and structured logging statements without sacrificing clarity. The key is to prioritize readability and logical grouping of code elements over strict adherence to a character count. If a line exceeds 160 characters but is more readable than the alternatives, it is acceptable. However, lines should not be excessively long or dense; use discretion to break lines at logical points (e.g., after method calls, between parameters) to enhance readability.
This applies to all source code, including XML documentation comments, where longer lines may be necessary for clarity. The goal is to write code that is easy to read and understand, not to conform to an arbitrary line length limit.
Source code should aim for a maximum line length of 160 characters.
Guidelines:
- Prefer readability over strict wrapping.
- Avoid wrapping fluent APIs or method chains unnecessarily.
- Long log messages, LINQ queries, and JSON payload builders may exceed this when it improves clarity.
- XML documentation comments may exceed this limit when needed.
Example (preferred):
logger.LogInformation("Published certificate state: StateQueue={StateQueue}, BroadcastExchange={Exchange}, NotAfter={NotAfter}",
StateQueueName, BroadcastExchangeName, current?.NotAfter);- Use
#region/#endregiondirectives to organize code sections within classes. - Standard region order: Constants, Fields, Properties, Constructors, Public Methods, Private Methods (grouped by responsibility), Nested Types.
- In
Program.cs, local functions are organized by region: Configuration, Process Tuning, Exception Handlers, Logging, Infrastructure, HTTP Clients. - Do not use decorative comment-block separators (e.g.,
// ═══... or // ───...) as section dividers.
| Element | Convention | Example |
|---|---|---|
| Private fields | _camelCase |
_reconcileLock, _poolSnapshots |
| Constants | PascalCase |
MaxBackOffMS, BaseRestartDelayMS |
| Static readonly | PascalCase |
PollInterval, JsonOptions |
| Public properties | PascalCase |
GrabberConfig, Hostname |
| Local variables | camelCase |
earlyConfig, minWorkerThreads |
| Parameters | camelCase |
stoppingToken, workerCount |
| Enum values | PascalCase |
Found, WaitingToRestart |
| Config section names | const string |
public const string SectionName = "..." |
All enums in the NNRPD.Radius namespace that represent RADIUS Attribute Names, Attribute Values, or Packet Codes are an intentional exception to the PascalCase enum convention above. These identifiers use SCREAMING_CASE (UPPER_SNAKE_CASE) to maintain a 1:1 correspondence with the canonical IANA RADIUS dictionary names and RFC definitions.
This applies to:
RadiusCode— packet type codes (e.g.,ACCESS_REQUEST,ACCOUNTING_RESPONSE).RadiusAttributeType— attribute type identifiers (e.g.,USER_NAME,NAS_IP_ADDRESS,SERVICE_TYPE).- Attribute value enums —
SERVICE_TYPE,FRAMED_PROTOCOL,FRAMED_ROUTING,FRAMED_COMPRESSION,LOGIN_SERVICE,TERMINATION_ACTION,ACCT_STATUS_TYPE,ACCT_AUTHENTIC,ACCT_TERMINATE_CAUSE,NAS_PORT_TYPE,TUNNEL_TYPE,TUNNEL_MEDIUM_TYPE,ARAP_ZONE_ACCESS,PROMPT,INGRESS_FILTERS_VALUE,ERROR_CAUSE,NAMESPACE_IDENTIFIER,LOCATION_PROFILES,LOCATION_INFORMATION_SOURCE,BASIC_LOCATION_POLICY_RULES,LOCATION_CAPABLE,REQUESTED_LOCATION_INFO,FRAMED_MANAGEMENT_PROTOCOL,MANAGEMENT_TRANSPORT_PROTECTION,EAP_LOWER_LAYER,FRAG_STATUS.
Do not:
- Rename these identifiers to PascalCase or any other convention.
- Apply IDE naming suggestions, code-style fixers, or bulk renames to these identifiers.
- Suppress or override the SCREAMING_CASE convention for any new RADIUS enum added to
RadiusEnums.cs.
Rationale: Renaming would break the direct mapping to the RADIUS protocol specification, make wire-level debugging harder, and invalidate .ToString() output used in structured logging and diagnostics.
- Time-related constants use a unit suffix:
msfor milliseconds,Secondsfor seconds.- Example:
MaxBackOffms = 60_000,DefaultKeepAliveSeconds = 120.
- Example:
- Use digit separators (
_) in large numeric literals for readability:60_000,1_099_511_627_776.
- Always specify explicit access modifiers on all types, members, and nested types.
- Prefer
sealedon classes that are not designed for inheritance. - Use
readonlyonrecord structtypes and fields wherever possible.
- The project has nullable reference types enabled globally.
- Use
?on types that are legitimately nullable; never suppress warnings with!unless a DI guarantee is documented.
Every public type, method, property, constant, and field must have a <summary> tag. No exceptions.
- Classes: Include
<summary>,<remarks>with lifecycle, thread-safety notes, and relationship to other types. - Methods: Include
<summary>,<remarks>(with numbered<list type="number">for multi-step flows),<param>,<returns>, and<exception>where applicable. - Properties: Include
<summary>,<remarks>explaining validation, default values, and how/where the property is consumed. - Constants / Fields: Include
<summary>and<remarks>explaining the value's derivation and where it is used.
- Use
<para>blocks inside<remarks>for paragraph separation. - Use bold lead-ins with
<b>tags:<b>Lifecycle:</b>,<b>Thread safety:</b>,<b>Failure handling:</b>. - Use
<list type="number">for sequential steps,<list type="bullet">for unordered items. - Use
<see cref="..." />for all cross-references to types, methods, properties, and parameters. - Use
<c>code</c>for inline code references (values, config keys, NNTP commands). - Use
<code>blocks for multi-line examples (e.g., JSON configuration snippets).
- Document each primary constructor parameter in the class-level
<summary>or<remarks>block, not separately above the parameter list.
/// <summary>
/// Sends a best-effort NNTP <c>QUIT</c> command and disposes all connection resources.
/// </summary>
/// <remarks>
/// <para>
/// <b>Best-effort:</b> The QUIT command is bounded by <see cref="QuitTimeout"/> (2 s). If the server is
/// unresponsive, the timeout fires and disposal proceeds immediately.
/// </para>
/// <para>
/// <b>Disposal order:</b>
/// </para>
/// <list type="number">
/// <item><description>Send QUIT command with timeout.</description></item>
/// <item><description>Dispose <see cref="PipeReader"/>.</description></item>
/// <item><description>Dispose <see cref="SslStream"/> (if TLS).</description></item>
/// <item><description>Dispose <see cref="Socket"/>.</description></item>
/// </list>
/// </remarks>
private async Task QuitAndDisposeAsync()
Each .cs file begins with a block comment summarizing the file's purpose, lifecycle, I/O architecture, and key call sequences. This is a plain // comment block (not XML doc), separated from the using directives by a blank line.
The first line must begin with the filename (with or without the .cs extension) followed by an em-dash (—) or double-hyphen (--) and a brief one-line summary of the file's responsibility:
// ConnectionHolder.cs — thread-safe singleton that holds the shared RabbitMQ IConnection.
For partial class files, include the partial-file suffix in the filename:
// NodeIdentity.Logging.cs — Source-generated [LoggerMessage] partial methods for NodeIdentity.
Subsequent lines provide additional detail: lifecycle, threading model, caller/callee relationships, cross-platform notes, and SIMD applicability.
- Use Serilog's structured logging with named placeholders (
{PropertyName}) instead of string interpolation. - Log property names use
PascalCase:{WorkerId},{Backbone},{ConfigEndpoint}.
All new logging should use the [LoggerMessage] source generator pattern from Microsoft.Extensions.Logging for compile-time validation, zero-allocation logging, and consistent structure:
- Classes receive
ILogger<T>via DI constructor injection. - Log methods are declared as
partialmethods with the[LoggerMessage]attribute. - Log methods are placed in a dedicated
*.Logging.cspartial file (e.g.,ConnectionFactory.Logging.cs). - Each
[LoggerMessage]method specifiesLevelandMessageexplicitly. - Event IDs should be unique within a class and assigned sequentially.
- Message strings must contain only ASCII characters (see ASCII-Only Log Messages below).
Example:
// ConnectionFactory.Logging.cs
internal sealed partial class ConnectionFactory
{
[LoggerMessage(Level = LogLevel.Information,
Message = "RabbitMQ connecting -- Endpoints=[{Endpoints}], VHost={VirtualHost}, SSL={EnableSsl}, " +
"Heartbeat={Heartbeat}s, Recovery={Recovery}s, FrameMax={FrameMax}")]
private partial void LogConnectionAttempt(string endpoints, string virtualHost, bool enableSsl,
double heartbeat, double recovery, uint frameMax);
}Exception note: Serilog's static Log.ForContext(...) pattern (Serilog.ILogger) should only be used in POCO types that cannot receive DI-injected loggers (e.g., RabbitMQOptions where IValidatableObject.Validate runs during options binding before DI is fully available).
All [LoggerMessage] Message strings must contain only ASCII characters (U+0020–U+007E). This ensures log
output is readable regardless of the terminal or log-viewer encoding (Windows-1252, Latin-1, UTF-8 without BOM).
Substitution rules for common Unicode characters:
| Unicode Character | Replacement | Example |
|---|---|---|
— (em-dash, U+2014) |
-- |
"Connection stalled -- reconnecting..." |
– (en-dash, U+2013) |
- |
"Range: [100-200]" |
→ (right arrow, U+2192) |
-> |
"{Source} -> {Target}" |
← (left arrow, U+2190) |
<- |
|
≥ (greater-or-equal, U+2265) |
>= |
|
≤ (less-or-equal, U+2264) |
<= |
Scope: This rule applies only to the Message string in [LoggerMessage] attributes. XML documentation
comments, file header comments, and C# source identifiers may continue to use Unicode characters since they
are not emitted to log output.
| Level | Usage |
|---|---|
Trace |
NNTP command/response wire-level detail (redacted credentials). |
Debug |
Per-article request lifecycle, throughput stats, client properties. |
Information |
Startup banners, connection established, pool created/scaled, periodic status. |
Warning |
Transient failures, config poll failures (< escalation threshold), non-standard configs. |
Error |
Sustained control-plane unavailability, unobserved task exceptions, callback exceptions. |
Fatal |
Configuration validation failure (hard-terminate), unhandled exceptions. |
- Always guard
TraceandDebuglog calls withlogger.IsEnabled(LogLevel.Xxx)when the message requires formatting or computation (e.g., throughput stats, client property enumeration).
- All configuration sections use the strongly-typed Options pattern with
IOptions<T>. - Options classes include a
public const string SectionNamefor the configuration key. - Validation uses
[Required],[Range],[Url], andIValidatableObjectfor cross-property checks. - Register with
.ValidateDataAnnotations().ValidateOnStart()in the DI pipeline.
- Dispose resources in a fixed order, each in its own
try/catchto prevent one failure from blocking subsequent disposals. - Use
Interlocked.Exchangefor double-dispose guards. - Use
finallyblocks for metric gauge decrements and resource cleanup to guarantee execution on all exit paths.
- Distinguish between global shutdown cancellation and individual worker cancellation using linked
CancellationTokenSource. - Always check
stoppingToken.IsCancellationRequestedincatch (OperationCanceledException)to differentiate timeout from shutdown.
Vector.NNTP.Utilities/README.md is the quick namespace map; this section is the contribution contract for that assembly.
- References BCL and
Microsoft.Extensions.Logging.Abstractionsonly. Do not add RabbitMQ, Certes, or other domain packages. - Add a new public namespace when a folder would exceed ~5 unrelated types or mixes hot-path binary operations with cold diagnostics.
- Add
Vector.NNTP.Utilities.Internalhelpers only when a pattern appears in 2+ call sites or when isolating throws from a hot loop (see Internal folder policy below).
Every Utilities .cs synopsis header must declare one of:
// HOT PATH: no LINQ; no allocations on success; no closures; no boxing; prefer Span/stackalloc; throws extracted + NoInlining where documented.
// COLD PATH: diagnostics/formatting/startup validation; readability over micro-optimization; allocations acceptable.
| HOT | COLD |
|---|---|
EncodingUtilities, DnsWireFormatUtilities, DnsWireQueryBuilder, DnsWireNameReader, AsciiSpanUtilities, LengthLimitedReadStream, RetryUtilities, EwmaUtilities, HostParsingUtilities, IPUtilities |
FormattingUtilities, EnvironmentUtilities, AssemblyInfoUtilities, DnsValidationUtilities, CredentialPlaceholderDetector, FileIOUtilities, DisposalUtilities, TaskUtilities |
Public types must include <remarks><para><b>Performance:</b> HOT PATH …</para></remarks> or the cold-path equivalent.
- stackalloc for bounded buffers (DNS label splits, small wire packets). Follow
DnsWireQueryBuilder— stack whenpacketLength <= MaxStackAllocQuerySize, heap fallback otherwise. - ArrayPool for temporary copy buffers: rent in
try, return infinallyviaInternal.PoolingHelpers(buffers are not cleared on return; callers overwrite via reads). - Error strings and diagnostic formatting may allocate; keep them off success paths in HOT types.
- Overload order: Span/Memory → string → async; optional parameters last.
- Add Span overloads when callers already hold spans; keep string APIs for configuration and logging.
- Do not introduce extension methods by default.
- Cold entry validation: BCL helpers (
ArgumentNullException.ThrowIfNull,ArgumentException.ThrowIfNullOrEmpty,ArgumentOutOfRangeException.ThrowIfNegative). - Hot or duplicated throws:
Vector.NNTP.Utilities.Internal.ThrowHelpersandSpanValidationHelpers. - Extract throws from hot loops; mark throw methods with
[DoesNotReturn]and[MethodImpl(MethodImplOptions.NoInlining)]when the throw would block inlining of the caller. - Domain-specific messages (DNS label errors, response limit exceeded) stay in the owning type — do not genericize.
- Use
*Asyncsuffix on asynchronous public APIs. - Document whether cancellation propagates (
OperationCanceledException) or maps to return false (TaskUtilities.DelayOrCancelledAsync, swallow-and-return helpers). - Use
ConfigureAwait(false)in library code unless a synchronization context is required (see repo-wide async guidance).
- Document thread safety on every public type in XML
<remarks>. - Stateless static helpers: safe for concurrent use.
- Instance types: document single-reader / caller-synchronised contracts explicitly.
Random.Sharedand immutable static caches (FrozenSet, cached delegates) are thread-safe; document them in type remarks.
- Use
[LoggerMessage]partial methods in companion*.Logging.csfiles (see Logging Standards above). - ASCII-only message strings in
[LoggerMessage]attributes.
- Follow the repo nullable section above. Do not use
!without a documented invariant in<remarks>.
- Changes to HOT PATH types require regression checks:
dotnet test VectorNNTP.NNTPD.slnx -p:Platform=x64plus a PR note when throughput or allocation behavior could change. - Add BenchmarkDotNet coverage when introducing new SIMD or pooling paths (project TBD).
Add to Internal/ when |
Do not add when |
|---|---|
| Same throw message in 2+ types | Only one consumer exists |
| Same span-length check in 2+ encode paths | Message or semantics differ by domain |
| ArrayPool rent/return duplicated | A one-line BCL call suffices |
| Disposed guard shared by instance types | A generic Validate<T> or catch-all Guard would result |
Current internal types: ThrowHelpers, SpanValidationHelpers, GuardUtilities, PoolingHelpers. Defer AsyncHelpers / ExceptionUtilities until a second consumer appears.