Skip to content

COMMENTING_GUIDE.md

Latest commit

 

History

History
54 lines (38 loc) · 2.84 KB

COMMENTING_GUIDE.md

File metadata and controls

54 lines (38 loc) · 2.84 KB
Raw

简体中文 | English · Back to README

Comments and public API documentation

Comments explain caller constraints, design rationale, and non-obvious behavior. They should not translate self-explanatory code line by line.

Public APIs

Every public or protected API and every interface member must use C# XML documentation:

  • <summary> explains purpose instead of repeating the member name.
  • Every parameter and type parameter has its own <param> or <typeparam>, including every overload.
  • Every non-void method has <returns> describing the value and important null or status semantics.
  • Use <exception> for exceptions callers are expected to handle and <remarks> for cost, concurrency, security, or platform constraints.
  • Use <inheritdoc /> when an implementation already has a complete interface or base-class contract.
  • Preserve identifier casing and suffixes when comments refer to code names, for example UserId, 用户Id, and 租户Id, rather than UserID or 用户 ID.
  • Let content determine punctuation: short labels normally omit terminal punctuation; complete statements, reasons and constraints use normal punctuation. Do not bulk-strip punctuation or rewrite license headers.

Bad:

/// <summary>Sets cache.</summary>
bool Set(string key, object value);

Preferred:

/// <summary>
/// Stores a value under the specified cache key.
/// </summary>
/// <param name="key">The cache key</param>
/// <param name="value">The value to store</param>
/// <returns><see langword="true"/> when the value is stored successfully; otherwise <see langword="false"/>.</returns>
bool Set(string key, object value);

Implementation comments

Comments are valuable for:

  • Concurrency order, double checks, lock scope, and cache-stampede protection.
  • Security boundaries such as token signature validation, trusted proxies, and output escaping responsibilities.
  • Cross-platform, encoding, reflection, runtime-loading, and third-party constraints.
  • Operations with significant cost or external blocking behavior.
  • Code that looks simplifiable but is constrained by a protocol or framework contract.

Do not retain commented-out code, ownerless TODO items, or conversational placeholders. Version control already preserves historical implementations.

Use <see cref="…"/> and <paramref name="…"/> for symbol and parameter references. Review generated XML as well as editor tooltips when using <inheritdoc/>.

Punctuation and scope

Short labels normally omit terminal punctuation. Complete statements, reasons and constraints use normal punctuation. Do not bulk-remove punctuation from XML documentation or ordinary comments; existing license headers are maintained separately. Public SDK contracts need more detail than internal implementation comments.