Add didactic comments across examples

Author: lucasbellesi

CONTRIBUTING.md

@@ -88,12 +88,11 @@ The public PowerShell and Bash scripts are thin wrappers over the shared Python
   - recommended `## Cross-Language Notes` before `## What To Check`
 - Every implemented level README should include required `## Learning Metadata` before `## Module Order` with `Difficulty`, `Estimated Time`, `Prerequisites`, and `Study Strategy`.
 - Checkpoint README structure should mirror the matching C++ checkpoint style, not the module README contract.
-- Every `example/main.*` file should include intent-first comments for:
-  - program flow,
-  - input/validation blocks,
-  - core algorithm or transformation blocks,
-  - important branching decisions,
-  - output/verification sections.
+- Every hand-written code file under `example/` should include intent-first comments:
+  - a short file header comment that explains what the example teaches
+  - comments before program flow, validation, core transformation, branching, or output blocks when those blocks are non-trivial
+  - language-specific notes when the example is an adaptation rather than a direct translation of the C++ concept
+  - no empty scaffolding comments such as `Intent:` and no line-by-line narration of obvious syntax
 - Every exercise file must contain complete, runnable content.
 - Avoid external dependencies and test frameworks for C++ modules.
 - Avoid external dependencies and test frameworks for non-C++ checkpoints.

README.md

@@ -138,11 +138,13 @@ Checkpoint artifacts under `languages/<language>/projects/*` and `languages/<lan
 
 ## Example Commenting Standard
 
-Example files (`example/main.*`) should use intent-first comments to help new developers read code quickly:
+Hand-written example code files under `languages/*/*/*/example/` should use intent-first comments to help new developers read code quickly:
 
-- Explain purpose, intent, and edge-case handling.
-- Place comments before meaningful logic blocks (not every single line).
+- Start each file with a short header comment that explains what the example teaches.
+- Place comments before meaningful logic blocks, validation paths, and output/verification sections.
+- Use comments to explain concepts, tradeoffs, and language-specific adaptations, not obvious syntax.
 - Keep comments short, practical, and in English.
+- Avoid empty scaffolding comments such as `Intent:` or line-by-line narration.
 
 ## Validation and CI
 

languages/cpp/01-foundations/arrays-and-vectors/example/main.cpp

@@ -1,20 +1,20 @@
-// This example demonstrates arrays and vectors concepts.
-// Example purpose: show the module flow with clear, beginner-friendly steps.
+// This example shows storing related values in ordered collections and iterating safely.
+// In C++, the example keeps value flow, references, and explicit control visible.
 
 #include <iostream>
 #include <vector>
 using namespace std;
 
+// Run one deterministic scenario so the console output makes storing related values in ordered
+// collections and iterating safely easy to verify.
 int main() {
-    // Program flow: collect input, apply core logic, then print a verifiable result.
+    // Build the sample state first, then let the later output confirm the behavior step by step.
     const int fixedScores[3] = {72, 88, 95};
 
-    // Intent: print intermediate or final output for quick behavior verification.
+    // Print the observed state here so learners can connect the code path to a concrete result.
     cout << "Fixed array values: ";
-    // Intent: iterate through data in a clear and deterministic order.
     for (int i = 0; i < 3; ++i) {
         cout << fixedScores[i];
-        // Intent: guard invalid or edge-case paths before the main path continues.
         if (i < 2) {
             cout << ", ";
         }
@@ -23,7 +23,6 @@ int main() {
 
     int count = 0;
     cout << "How many temperatures do you want to enter? ";
-    // Intent: gather typed input first so later operations are predictable.
     cin >> count;
 
     if (count <= 0) {

languages/cpp/01-foundations/arrays-and-vectors/example/vector-filter.cpp

@@ -1,3 +1,6 @@
+// This helper example focuses on isolating one collection transformation so the filtering rule
+// stands out.
+
 #include <iostream>
 #include <vector>
 

languages/cpp/01-foundations/control-flow/example/main.cpp

@@ -1,18 +1,18 @@
-// This example demonstrates control flow concepts.
-// Example purpose: show the module flow with clear, beginner-friendly steps.
+// This example shows choosing between branches and repeating work with predictable control flow.
+// In C++, the example keeps value flow, references, and explicit control visible.
 
 #include <iostream>
 using namespace std;
 
+// Run one deterministic scenario so the console output makes choosing between branches and
+// repeating work with predictable control flow easy to verify.
 int main() {
-    // Program flow: collect input, apply core logic, then print a verifiable result.
+    // Build the sample state first, then let the later output confirm the behavior step by step.
     int value = 0;
-    // Intent: print intermediate or final output for quick behavior verification.
+    // Print the observed state here so learners can connect the code path to a concrete result.
     cout << "Enter an integer: ";
-    // Intent: gather typed input first so later operations are predictable.
     cin >> value;
 
-    // Intent: guard invalid or edge-case paths before the main path continues.
     if (value > 0) {
         cout << value << " is positive.\n";
     } else if (value < 0) {
@@ -29,7 +29,6 @@ int main() {
         cout << "Factorial is not defined for negative integers.\n";
     } else {
         unsigned long long factorial = 1;
-        // Intent: iterate through data in a clear and deterministic order.
         for (int i = 1; i <= n; ++i) {
             factorial *= static_cast<unsigned long long>(i);
         }

languages/cpp/01-foundations/control-flow/example/menu-loop.cpp

@@ -1,3 +1,6 @@
+// This helper example focuses on focusing on the repeated menu interaction without distracting
+// setup code.
+
 #include <iostream>
 
 using namespace std;

languages/cpp/01-foundations/formatted-output-and-iomanip/example/main.cpp

@@ -1,12 +1,14 @@
-// This example demonstrates formatted output and iomanip concepts.
-// Example purpose: show the module flow with clear, beginner-friendly steps.
+// This example shows formatting values so output is easier to read and compare.
+// In C++, the example keeps value flow, references, and explicit control visible.
 
 #include <iomanip>
 #include <iostream>
 using namespace std;
 
+// Run one deterministic scenario so the console output makes formatting values so output is easier
+// to read and compare easy to verify.
 int main() {
-    // Program flow: collect input, apply core logic, then print a verifiable result.
+    // Build the sample state first, then let the later output confirm the behavior step by step.
     const char* item1 = "Notebook";
     const char* item2 = "Pen";
     const char* item3 = "Backpack";
@@ -15,7 +17,7 @@ int main() {
     const double p2 = 1.2;
     const double p3 = 30.0;
 
-    // Intent: print intermediate or final output for quick behavior verification.
+    // Print the observed state here so learners can connect the code path to a concrete result.
     cout << left << setw(12) << "Item" << right << setw(10) << "Price" << '\n';
     cout << "----------------------\n";
 

languages/cpp/01-foundations/functions/example/function-overload-basics.cpp

@@ -1,8 +1,12 @@
+// This helper example focuses on showing one focused overload or helper so the main example stays
+// easy to scan.
+
 #include <iostream>
 #include <string>
 
 using namespace std;
 
+// Keep this helper separate so the main example can focus on the larger idea without extra noise.
 void printValue(int value) { cout << "Integer value: " << value << '\n'; }
 
 void printValue(double value) { cout << "Double value: " << value << '\n'; }

languages/cpp/01-foundations/functions/example/main.cpp

@@ -1,10 +1,11 @@
-// This example demonstrates functions concepts.
-// Example purpose: show the module flow with clear, beginner-friendly steps.
+// This example shows breaking behavior into reusable functions with clear inputs and outputs.
+// In C++, the example keeps value flow, references, and explicit control visible.
 
 #include <iostream>
 #include <vector>
 using namespace std;
 
+// Define the reusable pieces first so the main flow can focus on one observable scenario.
 int sum(int a, int b) { return a + b; }
 
 void swapByReference(int& left, int& right) {
@@ -14,12 +15,9 @@ void swapByReference(int& left, int& right) {
 }
 
 void printVector(const vector<int>& values) {
-    // Intent: print intermediate or final output for quick behavior verification.
     cout << "[";
-    // Intent: iterate through data in a clear and deterministic order.
     for (size_t i = 0; i < values.size(); ++i) {
         cout << values[i];
-        // Intent: guard invalid or edge-case paths before the main path continues.
         if (i + 1 < values.size()) {
             cout << ", ";
         }
@@ -37,8 +35,11 @@ void incrementByReference(int& number) {
     cout << "Inside incrementByReference: " << number << '\n';
 }
 
+// Run one deterministic scenario so the console output makes breaking behavior into reusable
+// functions with clear inputs and outputs easy to verify.
 int main() {
-    // Program flow: collect input, apply core logic, then print a verifiable result.
+    // Build the sample state first, then let the later output confirm the behavior step by step.
+    // Print the observed state here so learners can connect the code path to a concrete result.
     cout << "sum(4, 6) = " << sum(4, 6) << '\n';
 
     int first = 10;

languages/cpp/01-foundations/operators-and-expressions/example/main.cpp

@@ -1,15 +1,17 @@
-// This example demonstrates operators and expressions concepts.
-// Example purpose: show the module flow with clear, beginner-friendly steps.
+// This example shows combining values through expressions and readable calculations.
+// In C++, the example keeps value flow, references, and explicit control visible.
 
 #include <iostream>
 using namespace std;
 
+// Run one deterministic scenario so the console output makes combining values through expressions
+// and readable calculations easy to verify.
 int main() {
-    // Program flow: collect input, apply core logic, then print a verifiable result.
+    // Build the sample state first, then let the later output confirm the behavior step by step.
     const int a = 17;
     const int b = 5;
 
-    // Intent: print intermediate or final output for quick behavior verification.
+    // Print the observed state here so learners can connect the code path to a concrete result.
     cout << "a = " << a << ", b = " << b << "\n\n";
     cout << "a + b = " << (a + b) << '\n';
     cout << "a - b = " << (a - b) << '\n';