CLAUDE CODE AGENTS: FUNDAMENTALS - Chapter 9, Exercise 2
README "What" vs. Inline Comment "Why"
====================================================================================

QUESTION:
Explain the distinction this chapter draws between what a README should
describe and what an inline code comment should describe, and why a
documentation agent needs to know the difference.

SOLUTION / EXPLANATION:

This chapter draws a specific, deliberate line between two different
writing contexts that both fall under "documentation" broadly, but serve
genuinely different readers and purposes.

A README or API doc is written for a reader who has never seen this code
before and needs to understand WHAT it does and how to use it - describing
behavior, inputs, outputs, and usage is exactly the right content for this
context, since that's the entire point of the document existing at all.

An inline code comment, by contrast, is written for someone already reading
the actual code line by line. This chapter is explicit that such a comment
should stay minimal, and focus only on non-obvious WHY - a hidden
constraint, a subtle workaround, a reason behind a choice that wouldn't be
apparent just from reading well-named code. Restating what the code already
makes clear through good naming ("this loop iterates over users" written
above a loop that obviously does exactly that) adds clutter without adding
real information the reader doesn't already have.

A documentation agent needs to know this distinction because writing the
wrong kind of content in the wrong place actively hurts each context: a
README that assumes too much prior familiarity fails its actual readers,
while inline comments that restate the obvious "what" clutter the code
without adding real value it doesn't already communicate on its own. Knowing
which context it's writing in - and matching its content and style to that
context specifically - is part of doing the job correctly, not an
incidental detail.

--------------------------------------------------------------------------
WHY THIS WORKS AS AN ANSWER:
It states the specific difference (what vs. why) precisely, ties each to
who the actual reader is (a newcomer vs. someone already reading the code),
and explains concretely why writing the wrong kind of content in either
context is a real mistake, not a stylistic preference.