• What is SRP — and why do comments matter?
  • Anatomy of a great SRP comment
  • Bad comment vs. good comment
    • ❌ Bad — restates the obvious
    • ✅ Good — enforces the boundary
  • Inline comments that explain the boundary
  • Quiz — Which comment is SRP-compliant?
  • Drag & Drop — sort comments by class
  • Quiz — What should an inline comment explain?
  • Lesson complete!

    • from IPython.display import HTML, display display(HTML(“””

    XP — Single Responsibility Principle: Code Comments
    ★ 0 / 500 XP
    1

    What is SRP — and why do comments matter?

    SOLID · S Design Principle

    The Single Responsibility Principle says every class should have one job and one job only. A class that does too many things becomes impossible to maintain — changing one part breaks another.

    But SRP doesn't stop at how you split your classes. Comments are the contract — they tell future readers (and your teacher during live review) exactly what each class is responsible for, and just as importantly, what it deliberately doesn't do.

    💡 Think of a good SRP comment like a job description. It names the role, lists the duties, and makes clear what's out of scope.

    In the AutoTriage backend, four Java classes each own a single layer:

    ActivityEvent
    Carries session data — nothing else
    ActivityRepository
    Stores and retrieves data — nothing else
    ActivityService
    Applies business rules — nothing else
    DigestGenerator
    Builds Claude prompt — nothing else
    2

    Anatomy of a great SRP comment

    A great class-level comment does three things. Read the real comment from ActivityService.java:

    /** * ActivityService — Business Logic Layer * * Single Responsibility: Apply business rules to activity data. * Decides what counts as a valid session, when a student is inactive, * and whether a session is worth turning into a GitHub issue. * * Does NOT handle HTTP, Slack formatting, or Claude calls. * Those belong to ActivityController, SlackNotifier, and ClaudeClient. * * Constants here are the single source of truth for business thresholds. * Change them here — nothing else needs to update. * * Layer position: Service (middle of the stack) * Depends on: ActivityRepository * Called by: ActivityController, DigestGenerator */
    🎯
    1. State the job
    "Apply business rules to activity data"
    🚫
    2. State what it won't do
    "Does NOT handle HTTP, Slack, or Claude calls"
    🔗
    3. Name its neighbors
    "Depends on Repository, called by Controller"
    3

    Bad comment vs. good comment

    See the difference between a comment that just restates the code, and one that enforces SRP boundaries:

    ❌ Bad — restates the obvious

    /** * This class saves events. * It has a save method and * a findByUsername method. */ public class ActivityRepository {

    Tells you nothing you couldn't read from the code itself. Wastes the reader's time.

    ✅ Good — enforces the boundary

    /** * Persistence layer only. * Answers data questions — * never interprets results. * Business logic → Service. */ public class ActivityRepository {

    Makes the SRP boundary explicit. Future you will thank present you.

    👉 The best comments explain why logic lives here and not somewhere else. That's the SRP boundary made visible.
    4

    Inline comments that explain the boundary

    Inline comments should explain decisions, not describe syntax. From the real ActivityService.java:

    // Constructor injection keeps this testable — // swap a mock repo in unit tests without touching this class. private final ActivityRepository repository; // Rejects empty file lists before they reach the repository. // Business rule enforced here — not in the model, not in the controller. public void recordSession(ActivityEvent event) { if (event.getFilesModified() == null) { throw new IllegalArgumentException("..."); } repository.save(event); } // "Inactive" is a business concept — INACTIVE_THRESHOLD_HOURS // lives here so Mortensen can tune it without hunting magic numbers. private static final int INACTIVE_THRESHOLD_HOURS = 48;

    Each comment answers: why does this line exist, and why does it live in this class?

    ?

    Quiz — Which comment is SRP-compliant?

    +100 XP

    You're writing the header comment for DigestGenerator.java, which builds the Claude prompt from activity data. Which comment best demonstrates SRP understanding?

    5

    Drag & Drop — sort comments by class

    +200 XP

    Each comment snippet belongs to exactly one class. Drag each tag into the correct zone, then click Check.

    No business logic. Carry data only.
    Answers data questions. Never interprets results.
    Decides what counts as a valid session.
    Produces strings only. Does not call Claude.
    Single source of truth for business thresholds.
    ActivityEvent
    ActivityRepository
    ActivityService
    DigestGenerator
    ?

    Quiz — What should an inline comment explain?

    +100 XP

    You see this line in ActivityRepository.java:

    // ? private final List<ActivityEvent> store = new ArrayList<>();

    Which comment best explains this line in an SRP context?

    🏆

    Lesson complete!

    You understand how SRP-style comments enforce architectural boundaries.

    ★ 0 / 500 XP earned

    ”””))