refactor: improve code clarity and comments

Author: Tarawally

Sprint-3/quote-generator/app.js

@@ -1,22 +1,22 @@
 /* globals quotes, pickFromArray */
 
-// Use a constant for the auto-play time to make it easy to change later.
+// Defines the auto-play interval duration (60 seconds) as a constant for maintainability.
 const AUTO_PLAY_INTERVAL_MS = 60000;
 
-// Defines variables to track the state of the app.
-// Uses 'let' because the timer ID will change when we start/stop auto-play.
+// Tracks the state of the auto-play timer.
+// Initializes as null to indicate no active timer.
 let autoPlayIntervalId = null;
 
-// DOM Elements (fetched once to keep the code efficient)
+// Caches DOM references to avoid repeated lookups during runtime.
 const quoteElement = document.getElementById("quote");
 const authorElement = document.getElementById("author");
 const newQuoteButton = document.getElementById("new-quote");
 const autoPlaySwitch = document.getElementById("auto-play-switch");
 const autoPlayStatus = document.getElementById("auto-play-status");
 
 /**
- * Selects and displays a new random quote from the quote list.
- * This function changes the text on the screen.
+ * Retrieves a random quote from the data source and updates the DOM.
+ * Updates both the quote text and the author name.
  */
 function displayNewQuote() {
   // Selects a random quote object from the global 'quotes' array.
@@ -28,69 +28,69 @@ function displayNewQuote() {
 }
 
 /**
- * Starts the auto-play feature.
- * This sets up a timer to automatically change the quote every few seconds.
+ * Initiates the auto-play feature.
+ * Establishes a recurring timer to refresh the displayed quote.
  */
 function startAutoPlay() {
-  // Clears any existing timer first to prevent multiple timers running at once.
+  // Clears any existing timer to prevent overlapping intervals.
   if (autoPlayIntervalId) {
     clearInterval(autoPlayIntervalId);
   }
 
-  // Shows the "auto-play: ON" status text to inform the user it is active.
+  // Activates the visual status indicator for auto-play.
   autoPlayStatus.classList.add("active");
 
-  // Sets a repeating timer that calls 'displayNewQuote' every 60000 milliseconds (60 seconds).
+  // Schedules the 'displayNewQuote' function to execute every 60 seconds.
   autoPlayIntervalId = setInterval(function () {
     displayNewQuote();
   }, AUTO_PLAY_INTERVAL_MS);
 }
 
 /**
- * Stops the auto-play feature.
- * This cancels the timer so the quotes stop changing automatically.
+ * Terminates the auto-play feature.
+ * Clears the active timer and resets the state.
  */
 function stopAutoPlay() {
-  // Checks if a timer exists, and if so, stops it.
+  // Verifies if a timer exists before attempting to clear it.
   if (autoPlayIntervalId) {
     clearInterval(autoPlayIntervalId);
     autoPlayIntervalId = null;
   }
 
-  // Hides the "auto-play: ON" status text.
+  // Deactivates the visual status indicator.
   autoPlayStatus.classList.remove("active");
 }
 
 /**
- * Handles the change event when the user toggles the auto-play switch.
- * Decides whether to start or stop auto-play based on the switch position.
+ * Manages the state change when the auto-play switch is toggled.
+ * Routes execution to start or stop auto-play based on the switch state.
  *
- * @param {Event} event - The event object from the click.
+ * @param {Event} event - The change event triggered by the checkbox.
  */
 function handleAutoPlayToggle(event) {
-  // Checks if the toggle switch is currently 'checked' (on).
+  // Evaluates the checked state of the toggle switch.
   if (event.target.checked) {
     startAutoPlay();
   } else {
     stopAutoPlay();
   }
 }
 
-// Adds an event listener to the "New quote" button.
-// When clicked, it shows a new quote and resets the auto-play timer if it's running.
+// Attaches a click event listener to the "New quote" button.
+// Triggers a manual update of the quote and resets the auto-play timer if active.
 newQuoteButton.addEventListener("click", function () {
   displayNewQuote();
 
-  // If auto-play is turned on, restarts the timer.
-  // This prevents the quote from changing immediately after the user manually clicks.
+  // Restarts the auto-play timer if the feature is currently enabled.
+  // Ensures the full interval elapses before the next automatic update.
   if (autoPlaySwitch.checked) {
     startAutoPlay();
   }
 });
 
-// Adds an event listener to the auto-play toggle switch.
-// When changed, it triggers the handleAutoPlayToggle function.
+// Attaches a change event listener to the auto-play toggle switch.
+// Invokes the handler function whenever the user interacts with the switch.
 autoPlaySwitch.addEventListener("change", handleAutoPlayToggle);
 
-// Displays a random quote immediately when the page loads so it isn't empty.
+// Initializes the view by displaying a random quote upon page load.
 displayNewQuote();

Sprint-3/quote-generator/style.css

@@ -31,12 +31,12 @@ body {
   max-width: 700px;
   text-align: center;
   position: relative;
-  /* Simple crisp shadow or none based on flat design of example, keeping slight shadow for visibility */
+  /* Applies a simple crisp shadow for visibility, maintaining the flat design aesthetic */
   box-shadow: 0 4px 6px rgba(0,0,0,0.1); 
 }
 
 h1 {
-  display: none; /* The example image doesn't show a visible title inside the card */
+  display: none; /* Hides the title as it is not visible in the reference design */
 }
 
 #quote {
@@ -45,39 +45,39 @@ h1 {
   color: var(--text-color);
   margin-bottom: 1.5rem;
   position: relative;
-  padding-left: 3rem; /* Space for the quote icon */
+  padding-left: 3rem; /* Reserves space for the decorative quote icon */
   text-align: left;
 }
 
 #quote::before {
-  content: '“'; /* Large quote mark using curved quotes */
+  content: '“'; /* Renders a large curved quote mark */
   font-size: 6rem;
   color: var(--primary-color);
   position: absolute;
   top: -1.5rem;
   left: -1rem;
   line-height: 1;
-  font-family: sans-serif; /* Quote marks often look better in sans-serif or specific fonts */
-  opacity: 1; /* Solid colour in example */
+  font-family: sans-serif; /* Uses sans-serif for the quote mark for better visual appeal */
+  opacity: 1; /* Maintains solid opacity matching the design */
 }
 
 #author {
   font-size: 1.1rem;
   color: var(--text-color);
   margin-bottom: 2.5rem;
   text-align: right;
-  font-style: italic; /* Authors are often italicised in this style */
+  font-style: italic; /* Applies italics to distinguish the author name */
 }
 
-/* Add dash before author if not present in JS, but here we style assuming content */
+/* Appends a dash before the author name if not dynamically added by JS */
 #author::before {
   content: '- ';
 }
 
 .controls {
   display: flex;
   flex-direction: column;
-  align-items: flex-end; /* Button aligned to right in some designs, or center. Example shows right or center. Let's align right to match typical 'next' flows or keep center if safer. Example looks right-aligned for button. */
+  align-items: flex-end; /* Aligns controls to the right to match typical progression flows */
 }
 
 button {
@@ -96,12 +96,12 @@ button:hover {
   opacity: 0.9;
 }
 
-/* Auto-play Switch - adjusting to fit the new theme */
+/* Auto-play Switch - adjusts layout to fit the theme */
 .auto-play-container {
   display: flex;
   align-items: center;
   gap: 1rem;
-  margin-top: 1rem; /* Separate from main button */
+  margin-top: 1rem; /* Separates the switch from the main action button */
   align-self: flex-end;
 }
 
@@ -132,9 +132,9 @@ button:hover {
   left: 0;
   right: 0;
   bottom: 0;
-  background-color: #e4e4e4; /* Light grey for off */
+  background-color: #e4e4e4; /* Sets light grey background for the 'off' state */
   transition: .4s;
-  border-radius: 0; /* Square/Rectangular look or keep rounded? Let's keep rounded for standard UI toggle */
+  border-radius: 0; /* Maintains square/rectangular shape for a standard toggle look */
 }
 
 .slider:before {