Intermediate
Code Comments
#readme
#documentation
README Code Sections
6 exercises — write clear Quick Start sections, annotated code blocks, and HTTP examples that developers can actually follow.
0 / 27 completed
1 / 27
A README shows:
````
```bash
npm install my-package
```
````
Then immediately shows a code block with no explanation. What is missing?
A one-sentence description and prerequisites — every code block in a README should be introduced by a prose sentence that tells the reader: what this command does, and what they need before running it.
Good README code block pattern:
What the prose line should answer:
• What the command does ("Installs the package and its dependencies")
• Prerequisites ("Requires Node.js ≥ 18", "Run as root", "Must be in the project directory")
• Expected outcome for long commands ("This may take 1–2 minutes on first run")
Language tag on the code fence (bash, js, python, yaml) enables syntax highlighting in GitHub and documentation tools — also important, but the question is about the missing surrounding prose.
Good README code block pattern:
## Installation Requires Node.js ≥ 18. Install the package with: ```bash npm install my-package ```
What the prose line should answer:
• What the command does ("Installs the package and its dependencies")
• Prerequisites ("Requires Node.js ≥ 18", "Run as root", "Must be in the project directory")
• Expected outcome for long commands ("This may take 1–2 minutes on first run")
Language tag on the code fence (bash, js, python, yaml) enables syntax highlighting in GitHub and documentation tools — also important, but the question is about the missing surrounding prose.
2 / 27
Which Quick Start section is better written?
Option B — better Quick Start section. Differences:
1. Introductory sentence: tells the reader what the commands collectively achieve ("clone, install, start")
2. Language tag:
3. One command per line: easier to run step by step, easier to spot errors
4. Post-command context: "The dev server runs at http://localhost:3000" — tells the reader what success looks like
Option A problems:
• No prose intro — reader must infer what each command does
• No language tag (no syntax highlighting)
• Commands chained with
• No indication of what success looks like
Quick Start writing principles:
• One clear action per step
• Say what the reader should see when it works ("You should see: Server running")
• Include the minimal number of commands to go from zero to working
1. Introductory sentence: tells the reader what the commands collectively achieve ("clone, install, start")
2. Language tag:
bash enables syntax highlighting3. One command per line: easier to run step by step, easier to spot errors
4. Post-command context: "The dev server runs at http://localhost:3000" — tells the reader what success looks like
Option A problems:
• No prose intro — reader must infer what each command does
• No language tag (no syntax highlighting)
• Commands chained with
&& on one line — if one fails, hard to see where• No indication of what success looks like
Quick Start writing principles:
• One clear action per step
• Say what the reader should see when it works ("You should see: Server running")
• Include the minimal number of commands to go from zero to working
3 / 27
You are annotating a configuration code block for other developers. Which annotation comment style is clearest?
Inline comments + brief intro sentence — the most effective approach for annotated READMEs.
Example of a well-annotated config block:
Good in-block comment patterns:
•
•
•
What NOT to do:
• All-text wall before the block — loses readers before they see the code
• Footnotes — require readers to scroll back and forth
• No annotation — readers won't know which fields are optional, what format to use, or what constraints apply
Example of a well-annotated config block:
Create `.env` in the project root. Required fields: ```env DATABASE_URL=postgres://user:pass@localhost:5432/mydb JWT_SECRET=your-secret-here # min 32 characters REDIS_URL=redis://localhost:6379 # optional; used for session caching MAX_WORKERS=4 # set to CPU core count ```
Good in-block comment patterns:
•
# min 32 characters — constraint not visible from the key name•
# optional; used for session caching — indicates what happens if omitted•
# set to CPU core count — recommendation, not a hard ruleWhat NOT to do:
• All-text wall before the block — loses readers before they see the code
• Footnotes — require readers to scroll back and forth
• No annotation — readers won't know which fields are optional, what format to use, or what constraints apply
4 / 27
How should you mark required vs. optional environment variables in README documentation?
Table or inline comments — two common patterns in real-world READMEs:
Markdown table approach:
Inline comment approach:
Choose based on project complexity:
• 2–4 variables → inline comments are enough
• 5+ variables with types, defaults, examples → Markdown table is clearer
• Public API documentation → table (users expect structured reference docs)
Always include: required/optional, the default value for optional variables, and what happens if an optional variable is missing.
Markdown table approach:
| Variable | Required | Default | Description | |---|---|---|---| | DATABASE_URL | Yes | — | PostgreSQL connection string | | REDIS_URL | No | None | Redis for caching (optional) | | PORT | No | 3000 | Server listen port |
Inline comment approach:
```env DATABASE_URL=postgres://... # required REDIS_URL=redis://... # optional, default: disabled PORT=3000 # optional, default: 3000 ```
Choose based on project complexity:
• 2–4 variables → inline comments are enough
• 5+ variables with types, defaults, examples → Markdown table is clearer
• Public API documentation → table (users expect structured reference docs)
Always include: required/optional, the default value for optional variables, and what happens if an optional variable is missing.
5 / 27
You write a code section that shows an HTTP request example. Which detail is most often forgotten and most important to include?
The expected response — request-only examples leave developers guessing whether their request worked.
Good HTTP example pattern:
What to always show alongside a request:
• Success response — status code + body
• Error response — at least one common error case
• Headers required — Authorization format, Content-Type if relevant
• Path parameter meaning — "usr_123" → explain the ID format if non-obvious
Good HTTP example pattern:
Authenticate and retrieve a user:
```http
GET /api/v1/users/usr_123
Authorization: Bearer <token>
```
**Response (200 OK):**
```json
{
"id": "usr_123",
"email": "alex@example.com",
"role": "admin"
}
```
**Error (404):**
```json
{
"error": "user_not_found",
"message": "No user with ID usr_123"
}
```What to always show alongside a request:
• Success response — status code + body
• Error response — at least one common error case
• Headers required — Authorization format, Content-Type if relevant
• Path parameter meaning — "usr_123" → explain the ID format if non-obvious
6 / 27
A README section says "See the docs." with a link. What should it say instead?
Option C — descriptive link text with a clear URL.
Link writing rules for README and technical documentation:
❌ Bad link text:
• "See the docs." — what docs? Which part?
• "Click here" — no information about the destination
• "here", "this", "link" — meaningless out of context
✓ Good link text pattern:
• Describe what the reader will find: "Full API reference, examples, and troubleshooting"
• Include the visible URL for printed/copy-pasted contexts
• Be specific about the destination: "JSDoc for the fetch() options object" not "documentation"
Why this matters in READMEs:
• GitHub renders Markdown — links are clickable but the text is what readers scan
• Screen readers announce link text, not URLs
• When a developer copies a README to a wiki or issue, bare "click here" becomes meaningless
• Specific link text helps readers decide whether to follow the link before clicking
Link writing rules for README and technical documentation:
❌ Bad link text:
• "See the docs." — what docs? Which part?
• "Click here" — no information about the destination
• "here", "this", "link" — meaningless out of context
✓ Good link text pattern:
• Describe what the reader will find: "Full API reference, examples, and troubleshooting"
• Include the visible URL for printed/copy-pasted contexts
• Be specific about the destination: "JSDoc for the fetch() options object" not "documentation"
Why this matters in READMEs:
• GitHub renders Markdown — links are clickable but the text is what readers scan
• Screen readers announce link text, not URLs
• When a developer copies a README to a wiki or issue, bare "click here" becomes meaningless
• Specific link text helps readers decide whether to follow the link before clicking
7 / 27
During a code review of a new feature for an e-commerce platform, Alice comments on Ben's PR: 'This function looks good, but could you add a comment explaining why you're using this particular algorithm? It seems a bit complex for just displaying product details.' Ben replies with:
// Calculate shipping cost
float shippingCost = calculateShipping(order);
What is the BEST response Ben should provide to Alice, considering best practices for code documentation?
Ben's original comment was insufficient because it lacked context and didn't address Alice's concern about the algorithm's complexity. While a simple explanation might be appropriate in some cases, Alice was specifically questioning the rationale behind using a potentially more complicated approach. The best response demonstrates understanding of why documentation is important – to clarify decisions and prevent future confusion or difficulty in maintaining the code. It proactively provides an explanation that aligns with the original question.
8 / 27
// Calculate shipping cost
number = calculateShipping(order);
Sarah, a senior developer, is reviewing David's code and comments: 'This comment doesn't really explain *why*
calculateShipping is being called. It just states that it is. We should be documenting the assumptions or constraints that led to this choice in the function itself.' What is the MOST appropriate response David could provide to Sarah, aiming for clear and helpful documentation?David's initial comment was too terse and lacked context. It simply stated *what* he did, not *why*. The correct answer demonstrates a deeper understanding by explaining the purpose of the function call – that it calculates shipping based on order details. This level of explanation is crucial for maintainability and helps other developers understand the rationale behind the code, addressing Sarah's concern about documenting assumptions or constraints.
9 / 27
// Calculate shipping cost
float shippingCost = calculateShipping(order);
During a code review, Liam asks Maya to explain the comment. Maya responds with: "I thought it was obvious that this function calculates the shipping cost based on the order." Which of the following is the MOST effective response Maya should provide to Liam, adhering to best practices for code documentation?
Maya's initial response demonstrates a common misconception: that obvious code should automatically be self-documenting. This isn't true – technical debt can accumulate quickly if developers don't explicitly state *why* something is done, especially when the logic might not be immediately apparent. Option 0 provides a concrete example of how to improve the comment by explaining the underlying factors influencing the calculation. Options 1 and 2 reinforce the incorrect assumption that obviousness equates to sufficient documentation; option 3 misinterprets the purpose of comments.
10 / 27
During a code review of a new API endpoint designed to retrieve user profile data, Daniel comments on Emily's PR: 'This function is great, but I'm not entirely clear on the rationale behind using this specific URL. Could you add a comment explaining why we're hitting this particular endpoint and what information it provides?' Emily responds with:
Which of the following responses is MOST appropriate for Emily to provide, adhering to best practices for code documentation?
// Get user profile data
const userData = getUserProfile(userId);
Which of the following responses is MOST appropriate for Emily to provide, adhering to best practices for code documentation?
The key here is to move beyond simply stating *what* the code does and explain *why*. Option 1 provides a minimal description, while option 2 explicitly states the purpose of the endpoint – retrieving user profile data and details it contains. Options 3 and 4 introduce irrelevant or potentially misleading information (deprecation status). Good documentation clarifies intent and context, which is what Emily needs to provide.
11 / 27
During a code review of a new feature for an e-commerce platform, Alice comments on Ben's PR: 'This function looks good, but could you add a comment explaining why you're using this particular algorithm? It seems a bit complex for just displaying product details.' Ben replies with:
// Calculate shipping cost
float shippingCost = calculateShipping(order);
What is the BEST response Ben should provide to Alice, considering best practices for code documentation?
Ben's original comment was insufficient because it lacked context and didn't address Alice's concern about the algorithm's complexity. While a simple explanation might be appropriate in some cases, Alice was specifically questioning the rationale behind using a potentially more complicated approach. The best response demonstrates understanding of why documentation is important – to clarify decisions and prevent future confusion or difficulty in maintaining the code. It proactively provides an explanation that aligns with the original question.
12 / 27
// Calculate shipping cost
number = calculateShipping(order);
Sarah, a senior developer, is reviewing David's code and comments: 'This comment doesn't really explain *why*
calculateShipping is being called. It just states that it is. We should be documenting the assumptions or constraints that led to this choice in the function itself.' What is the MOST appropriate response David could provide to Sarah, aiming for clear and helpful documentation?David's initial comment was too terse and lacked context. It simply stated *what* he did, not *why*. The correct answer demonstrates a deeper understanding by explaining the purpose of the function call – that it calculates shipping based on order details. This level of explanation is crucial for maintainability and helps other developers understand the rationale behind the code, addressing Sarah's concern about documenting assumptions or constraints.
13 / 27
// Calculate shipping cost
float shippingCost = calculateShipping(order);
During a code review, Liam asks Maya to explain the comment. Maya responds with: "I thought it was obvious that this function calculates the shipping cost based on the order." Which of the following is the MOST effective response Maya should provide to Liam, adhering to best practices for code documentation?
Maya's initial response demonstrates a common misconception: that obvious code should automatically be self-documenting. This isn't true – technical debt can accumulate quickly if developers don't explicitly state *why* something is done, especially when the logic might not be immediately apparent. Option 0 provides a concrete example of how to improve the comment by explaining the underlying factors influencing the calculation. Options 1 and 2 reinforce the incorrect assumption that obviousness equates to sufficient documentation; option 3 misinterprets the purpose of comments.
14 / 27
During a code review of a new API endpoint designed to retrieve user profile data, Daniel comments on Emily's PR: 'This function is great, but I'm not entirely clear on the rationale behind using this specific URL. Could you add a comment explaining why we're hitting this particular endpoint and what information it provides?' Emily responds with:
Which of the following responses is MOST appropriate for Emily to provide, adhering to best practices for code documentation?
// Get user profile data
const userData = getUserProfile(userId);
Which of the following responses is MOST appropriate for Emily to provide, adhering to best practices for code documentation?
The key here is to move beyond simply stating *what* the code does and explain *why*. Option 1 provides a minimal description, while option 2 explicitly states the purpose of the endpoint – retrieving user profile data and details it contains. Options 3 and 4 introduce irrelevant or potentially misleading information (deprecation status). Good documentation clarifies intent and context, which is what Emily needs to provide.
15 / 27
During a code review of a new feature for an e-commerce platform, Alice comments on Ben's PR: 'This function looks good, but could you add a comment explaining why you're using this particular algorithm? It seems a bit complex for just displaying product details.' Ben replies with:
// Calculate shipping cost
float shippingCost = calculateShipping(order);
What is the BEST response Ben should provide to Alice, considering best practices for code documentation?
Ben's original comment was insufficient because it lacked context and didn't address Alice's concern about the algorithm's complexity. While a simple explanation might be appropriate in some cases, Alice was specifically questioning the rationale behind using a potentially more complicated approach. The best response demonstrates understanding of why documentation is important – to clarify decisions and prevent future confusion or difficulty in maintaining the code. It proactively provides an explanation that aligns with the original question.
16 / 27
// Calculate shipping cost
number = calculateShipping(order);
Sarah, a senior developer, is reviewing David's code and comments: 'This comment doesn't really explain *why*
calculateShipping is being called. It just states that it is. We should be documenting the assumptions or constraints that led to this choice in the function itself.' What is the MOST appropriate response David could provide to Sarah, aiming for clear and helpful documentation?David's initial comment was too terse and lacked context. It simply stated *what* he did, not *why*. The correct answer demonstrates a deeper understanding by explaining the purpose of the function call – that it calculates shipping based on order details. This level of explanation is crucial for maintainability and helps other developers understand the rationale behind the code, addressing Sarah's concern about documenting assumptions or constraints.
17 / 27
// Calculate shipping cost
float shippingCost = calculateShipping(order);
During a code review, Liam asks Maya to explain the comment. Maya responds with: "I thought it was obvious that this function calculates the shipping cost based on the order." Which of the following is the MOST effective response Maya should provide to Liam, adhering to best practices for code documentation?
Maya's initial response demonstrates a common misconception: that obvious code should automatically be self-documenting. This isn't true – technical debt can accumulate quickly if developers don't explicitly state *why* something is done, especially when the logic might not be immediately apparent. Option 0 provides a concrete example of how to improve the comment by explaining the underlying factors influencing the calculation. Options 1 and 2 reinforce the incorrect assumption that obviousness equates to sufficient documentation; option 3 misinterprets the purpose of comments.
18 / 27
During a code review of a new API endpoint designed to retrieve user profile data, Daniel comments on Emily's PR: 'This function is great, but I'm not entirely clear on the rationale behind using this specific URL. Could you add a comment explaining why we're hitting this particular endpoint and what information it provides?' Emily responds with:
Which of the following responses is MOST appropriate for Emily to provide, adhering to best practices for code documentation?
// Get user profile data
const userData = getUserProfile(userId);
Which of the following responses is MOST appropriate for Emily to provide, adhering to best practices for code documentation?
The key here is to move beyond simply stating *what* the code does and explain *why*. Option 1 provides a minimal description, while option 2 explicitly states the purpose of the endpoint – retrieving user profile data and details it contains. Options 3 and 4 introduce irrelevant or potentially misleading information (deprecation status). Good documentation clarifies intent and context, which is what Emily needs to provide.
19 / 27
During a code review of a new feature for an e-commerce platform, Alice comments on Ben's PR: 'This function looks good, but could you add a comment explaining why you're using this particular algorithm? It seems a bit complex for just displaying product details.' Ben replies with:
// Calculate shipping cost
float shippingCost = calculateShipping(order);
What is the BEST response Ben should provide to Alice, considering best practices for code documentation?
Ben's original comment was insufficient because it lacked context and didn't address Alice's concern about the algorithm's complexity. While a simple explanation might be appropriate in some cases, Alice was specifically questioning the rationale behind using a potentially more complicated approach. The best response demonstrates understanding of why documentation is important – to clarify decisions and prevent future confusion or difficulty in maintaining the code. It proactively provides an explanation that aligns with the original question.
20 / 27
// Calculate shipping cost
number = calculateShipping(order);
Sarah, a senior developer, is reviewing David's code and comments: 'This comment doesn't really explain *why*
calculateShipping is being called. It just states that it is. We should be documenting the assumptions or constraints that led to this choice in the function itself.' What is the MOST appropriate response David could provide to Sarah, aiming for clear and helpful documentation?David's initial comment was too terse and lacked context. It simply stated *what* he did, not *why*. The correct answer demonstrates a deeper understanding by explaining the purpose of the function call – that it calculates shipping based on order details. This level of explanation is crucial for maintainability and helps other developers understand the rationale behind the code, addressing Sarah's concern about documenting assumptions or constraints.
21 / 27
// Calculate shipping cost
float shippingCost = calculateShipping(order);
During a code review, Liam asks Maya to explain the comment. Maya responds with: "I thought it was obvious that this function calculates the shipping cost based on the order." Which of the following is the MOST effective response Maya should provide to Liam, adhering to best practices for code documentation?
Maya's initial response demonstrates a common misconception: that obvious code should automatically be self-documenting. This isn't true – technical debt can accumulate quickly if developers don't explicitly state *why* something is done, especially when the logic might not be immediately apparent. Option 0 provides a concrete example of how to improve the comment by explaining the underlying factors influencing the calculation. Options 1 and 2 reinforce the incorrect assumption that obviousness equates to sufficient documentation; option 3 misinterprets the purpose of comments.
22 / 27
During a code review of a new API endpoint designed to retrieve user profile data, Daniel comments on Emily's PR: 'This function is great, but I'm not entirely clear on the rationale behind using this specific URL. Could you add a comment explaining why we're hitting this particular endpoint and what information it provides?' Emily responds with:
Which of the following responses is MOST appropriate for Emily to provide, adhering to best practices for code documentation?
// Get user profile data
const userData = getUserProfile(userId);
Which of the following responses is MOST appropriate for Emily to provide, adhering to best practices for code documentation?
The key here is to move beyond simply stating *what* the code does and explain *why*. Option 1 provides a minimal description, while option 2 explicitly states the purpose of the endpoint – retrieving user profile data and details it contains. Options 3 and 4 introduce irrelevant or potentially misleading information (deprecation status). Good documentation clarifies intent and context, which is what Emily needs to provide.
23 / 27
During a Slack conversation about a new payment processing integration, Alex sends the following message: `// Process payment using Stripe API`. Ben replies: 'Could you add a comment explaining *why* we're using Stripe specifically? There are other providers.' Which of the following responses best addresses Ben's concern?
The key here is providing context *why* a choice was made. Option B is too dismissive and doesn't explain the rationale. Option A simply states popularity without justification. Option C offers to elaborate – that's the best approach for documentation. Option D focuses solely on integration, ignoring the broader decision.
24 / 27
You're writing a PR description for a new feature that calculates user session timeouts. The code includes this comment: `// Calculate timeout duration in seconds`. Reviewer Chris asks for more detail. Which of the following is the *most* appropriate addition to your PR description?
Chris needs to understand *why* the calculation is happening. Option A provides that explanation – it describes the purpose of the function. Options B and C are too technical and don't explain the rationale. Option D is overly broad and doesn't address Chris's question about the specific calculation.
25 / 27
During a standup meeting, Emily announces: `// Validate user input against schema`. Mark asks: 'Can you elaborate on *why* we're validating input this way? What are the potential consequences of not doing so?' Which of these responses would be most effective?
Mark's question highlights the importance of explaining *why* a decision was made. Option B clearly explains the purpose and benefits of using a schema for validation – data integrity and error prevention. The other options are either too general or focus on implementation details without addressing the core concern.
26 / 27
You're reviewing code that includes this: `// Fetch user profile data from API`. The API endpoint is documented as `/users/{userId}`. David asks: 'Could you add a comment explaining *why* we're using this specific URL? Is there a particular reason for the path structure?' What should you include in your response?
David wants context for *why* a particular URL was chosen. Option B simply states where it's defined and doesn't explain the rationale. Option C directly answers his question by detailing the purpose of the path structure – accessing profiles by ID. Options A & D are too generic.
27 / 27
In a code review, Rohan comments on Sarah's code: `// Calculate discount amount`. He asks: 'I'm not entirely clear on *why* you're using this formula. Could you add a comment explaining the logic behind it?' What is the MOST important piece of information to include in your response?
Rohan specifically wants to know *why* the formula was chosen. Option A provides that critical context – explaining the logic behind the discount calculation. The other options are either too technical (database definition, efficiency) or simply state it's a standard formula without justification.
Frequently Asked Questions
What will I practice in "README Code Sections — Code Comments Exercises"?
This is a Code Comments exercise set. It walks through 27 scenario-based multiple-choice questions built around real usage of Code Comments terminology that IT professionals encounter on the job.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to complete with no account, sign-up, or paywall.
How many questions are in this exercise?
This set contains 27 questions. Each one shows immediate feedback and a detailed explanation after you answer, so you learn the correct usage right away rather than waiting for a final score.
Do I need prior experience to complete this exercise?
No prior experience is required. Each question includes a full explanation covering the reasoning behind the correct answer, so the exercise itself teaches the Code Comments vocabulary as you go.
Can I retry the exercise if I get questions wrong?
Yes — use the "Try again" button on the results screen to reset your answers and go through all the questions again. There is no limit on attempts.
Is my progress saved?
Your answers and score for the current session are tracked in the browser as you go. No account or login is needed, and there is nothing to install.
What if I don't understand a term used in a question?
Read the explanation shown after you answer each question — it breaks down the correct term in plain English with a real-world example. You can also check the site Glossary for quick definitions.
How is this different from reading a blog article on the topic?
Exercises like this one are interactive drills that test and reinforce specific vocabulary through multiple-choice questions, while blog articles explain concepts in prose. Practising here after reading builds active recall, not just passive recognition.
Where can I find more Code Comments exercises?
See the Code Comments exercises hub for the full set of related pages, or browse all exercise categories from the main Exercises index.
Can I use this exercise to prepare for a technical interview?
Yes — Code Comments vocabulary comes up often in technical discussions and interviews. Pair this exercise with our dedicated Interview Preparation section for role-specific practice.