Add explanatory comments across codebase

Author: gabriele.sisinna

src/main/java/com/example/demo/DemoApplication.java

@@ -4,6 +4,7 @@
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 
 @SpringBootApplication
+// Standard Spring Boot entry point. Running main() starts the embedded server.
 public class DemoApplication {
 
 	public static void main(String[] args) {

src/main/java/com/example/demo/basics/annotations/LearningExample.java

@@ -7,6 +7,7 @@
 
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
+// Custom annotation used to tag classes with the concepts they are meant to teach.
 public @interface LearningExample {
 
 	String title();

src/main/java/com/example/demo/basics/exceptions/InvalidScoreException.java

@@ -1,5 +1,6 @@
 package com.example.demo.basics.exceptions;
 
+// Small custom exception that shows how domain rules can reject invalid input.
 public class InvalidScoreException extends RuntimeException {
 
 	public InvalidScoreException(String message) {

src/main/java/com/example/demo/basics/generics/Box.java

@@ -1,5 +1,6 @@
 package com.example.demo.basics.generics;
 
+// Generic class example: the same class can wrap different types safely.
 public class Box<T> {
 
 	private final T value;

src/main/java/com/example/demo/basics/inheritance/LearningStudent.java

@@ -1,5 +1,6 @@
 package com.example.demo.basics.inheritance;
 
+// Child class that inherits state from Person and overrides behavior.
 public class LearningStudent extends Person {
 
 	private final String track;

src/main/java/com/example/demo/basics/inheritance/Person.java

@@ -1,5 +1,6 @@
 package com.example.demo.basics.inheritance;
 
+// Parent class used to demonstrate inheritance and method overriding.
 public class Person {
 
 	private final String name;

src/main/java/com/example/demo/basics/interfaces/EmailNotifier.java

@@ -1,5 +1,6 @@
 package com.example.demo.basics.interfaces;
 
+// One implementation of the Notifier contract.
 public class EmailNotifier implements Notifier {
 
 	@Override

src/main/java/com/example/demo/basics/interfaces/Notifier.java

@@ -1,5 +1,6 @@
 package com.example.demo.basics.interfaces;
 
+// Interface example: callers depend on a contract, not a concrete implementation.
 public interface Notifier {
 
 	String channel();

src/main/java/com/example/demo/basics/model/Student.java

@@ -22,6 +22,7 @@
 		"annotations"
 	}
 )
+// Central plain-Java example used to teach fields, constructors, methods, collections, and control flow.
 public class Student {
 
 	private final long id;
@@ -47,6 +48,7 @@ public Student(
 		List<String> subjects,
 		Map<String, Integer> scores
 	) {
+		// Defensive copies keep callers from mutating the internal state by accident.
 		this.id = id;
 		this.name = name;
 		this.age = age;
@@ -60,13 +62,15 @@ public void activate() {
 	}
 
 	public void enroll(String subject) {
+		// Early return keeps invalid values out of the subjects list.
 		if (subject == null || subject.isBlank()) {
 			return;
 		}
 		this.subjects.add(subject.trim());
 	}
 
 	public void addScore(String subject, int score) {
+		// Throwing an exception is the explicit "fail fast" path for invalid state.
 		if (score < 0 || score > 100) {
 			throw new InvalidScoreException("Score must be between 0 and 100");
 		}
@@ -81,6 +85,7 @@ public String level() {
 	}
 
 	public int totalScore() {
+		// Classic for-each loop example over a Map's values.
 		int total = 0;
 		for (int value : scores.values()) {
 			total += value;
@@ -93,6 +98,7 @@ public String subjectSummary() {
 			return "No subjects yet";
 		}
 
+		// StringBuilder is efficient when building strings in a loop.
 		StringBuilder summary = new StringBuilder();
 		for (String subject : subjects) {
 			if (!summary.isEmpty()) {
@@ -104,6 +110,7 @@ public String subjectSummary() {
 	}
 
 	public Student withId(long newId) {
+		// Returns a new instance instead of mutating the id after construction.
 		return new Student(newId, name, age, active, subjects, scores);
 	}
 

src/main/java/com/example/demo/basics/streams/StudentAnalytics.java

@@ -6,6 +6,7 @@
 import java.util.Map;
 import java.util.stream.Collectors;
 
+// Stream examples that transform a list of students into derived data.
 public class StudentAnalytics {
 
 	public List<String> activeStudentNames(List<Student> students) {