Course contentsShow
← Software Engineering
Lesson 1684 of 1,93349. Technical Writing and DocumentationFree lesson

Code Comments and Inline Documentation

Explanatory text within source code clarifying complex logic, assumptions, and non-obvious decisions.

Code Comments and Inline Documentation

You'll learn how to use explanatory text within source code to clarify complex logic, document assumptions, and explain non-obvious decisions.

What Are Code Comments?

Code comments are annotations embedded directly in your source files that explain why and how code works. Unlike external documentation (README files, API references), comments live right alongside the code they describe, making them immediately accessible to anyone reading that section.

Think of comments as Post-it notes attached to specific lines or blocks of code—they provide context that isn't obvious from reading the code alone.

Why Comments Matter

Well-written code should be self-explanatory through clear variable names and logical structure. However, comments fill critical gaps:

  • Complex algorithms: When implementing a sophisticated sorting algorithm or mathematical formula
  • Business logic: Explaining why a particular calculation or rule exists ("Tax rate changes after midnight on Jan 1")
  • Workarounds: Documenting temporary fixes ("TODO: Remove after API v3 migration")
  • Assumptions: Clarifying constraints ("Assumes input array is pre-sorted")
  • Non-obvious decisions: Explaining why you chose approach A over seemingly simpler approach B

What NOT to Comment

Avoid stating the obvious. i++; // increment i adds no value. Your comments should answer "why," not "what"—the code itself already shows what it does.

Best Practices

Keep comments concise, accurate, and up-to-date. Outdated comments are worse than no comments—they mislead future developers (including yourself). Update comments whenever you modify the associated code.

Key Takeaway: Code comments and inline documentation clarify complex logic, business rules, assumptions, and non-obvious decisions that aren't apparent from reading the code itself, helping future maintainers (including your future self) understand not just what the code does, but why it does it that way.