wellcommented

Wellcommented is an adjective used in software development to describe source code that includes clear, accurate, and purposeful comments. Wellcommented code provides explanations for non-obvious logic, design decisions, interfaces, and edge cases, while avoiding unnecessary commentary on obvious steps.

Guidelines emphasize commenting what and why, not how. Comments should explain intent, constraints, and trade-offs, and should be kept up to date as code evolves. Public APIs are often documented with structured doc comments or inline documentation standardized by the language (for example, docstrings, Javadoc, or JSDoc).

Benefits include easier maintenance, faster onboarding for new contributors, and reduced debugging time. Well-documented code also aids code reviews and helps automated tooling generate documentation or ensure interface contracts.

Best practices include writing concise, precise comments; avoiding redundancy with readable code; placing comments near relevant code blocks; distinguishing between rationale and descriptive notes; updating comments with code changes; using consistent terminology across a project.

Challenges include the risk of stale comments, time pressure leading to under-commenting, and the tension between verbosity and readability. Teams may adopt lightweight conventions or code-first approach to minimize misalignment.

Related concepts include self-documenting code, API documentation standards, and documentation tooling; languages and frameworks may provide lint rules or guidelines to enforce comment quality.