Problem Decomposition and Pseudo-Coding

Most new web developers find it challenging to go from following tutorials to building projects on their own. In this post, I will take you through the steps you would take to get you from project description to beginning to code out the project. By the time you write your first line of code for a project, you should already know exactly what you will be coding out, and it shouldn't feel like an overwhelming task.

There are three steps prior to writing code.

1. Read and re-read the problem or project description to make sure you understand it well. If you can, ask any questions of your client. If it's an assignment or an algorithm with technical language, feed the description into an AI of your choice and ask it to rephrase it in simple language, without giving you any answers. I recommend turning the description into a list, as I exemplify below.
2. Project decomposition: you need to break down the project into small parts and ordered tasks. I find the easiest way to do this is to first write out user stories and developer stories, so that is what I model down below.
3. Finally, set yourself up for success by writing out the pseudo-code for the project in comment lines. Pseudo-code is using your natural language (i.e., English in my case) to describe what needs to be done, step by step. After this, you can get a good start by writing out your function stubs, as I show in the example below. This ensures that you have thought through the logic in advance.

Overall, the process of preparing to code is one of separating your thinking about what needs to be done, from how to do it (with code). If you think back to writing papers in school, this is like separating your writing a first draft from the editing process that makes that writing good. If you try to edit as you write, your writing will suffer. Same with code, the process of thinking through the problem in as much detail as you can, before actually writing the code, makes everything easier. Once you have it working, you can come back to your code with questions about how to improve your code, which involves another set of questions and skills.

I promise that, if you follow this process, writing code that is original and comes from you is 99.99% easier and more enjoyable.

The Project Description: Random Quote Generator¶

Create a web application that displays a random quote on the page. The application should have a button that, when clicked, generates a new random quote. The quotes can be stored in an array within the JavaScript file. Additionally, you can include an author name for each quote and display it along with the quote text.

Understand the Requirements¶

Start by turning the project description into a list¶

• The project requires creating a web application that displays a random quote on the page.
• There should be a button that, when clicked, generates a new random quote.
• The quotes should be stored in an array within the JavaScript file.
• The application should display the quote text and the author's name.

Now, think of the project from the perspective of the end user, and then from the perspective of the developer that needs to build it:

User Stories¶

User stories help to define the requirements and expectations from the perspective of the end-users, ensuring that the application meets their needs and provides a positive user experience.

• As a user, I want to see an initial quote and its author displayed on the page when I first load the application.
• As a user, I want to be able to click a button to generate a new random quote and author.
• As a user, I want to see a different quote and author each time I click the button to generate a new quote.
• As a user with disabilities, I want the application to be accessible and follow best practices for web accessibility. (Stretch goal)
• As a user, I want to be able to customize the styling of the quote display area and the button to match my preferences. (Stretch goal.)
• As a user, I want to be able to share the current quote and author on social media platforms or copy the text to the clipboard. (Stretch goal.)

Developer Stories¶

Developer stories are about capturing what are the concerns that the developer brings to the project:

• As a developer, I want to organize my code in a modular and maintainable way, separating concerns between HTML, CSS, and JavaScript files.
• As a developer, I want to store a collection of quotes and their authors in an array within the JavaScript file.
• As a developer, I want the quote and author to be displayed in a clear and readable format.
• As a developer, I want to include clear and concise comments in my code to explain the purpose and functionality of different sections, making it easier for other developers (or my future self) to understand and maintain the codebase.
• As a developer, I want the application to be responsive and display properly on different screen sizes and devices. (Stretch goal.)
• As a developer, I want to ensure that the application works consistently across different web browsers and versions. (Stretch goal.)
• As a developer, I want to optimize the application's performance by minimizing unnecessary computations, reducing file sizes, and implementing best practices for efficient rendering and execution. (Stretch goal.)

Write down everything you can think of, then go back through them and identify which goals are part of a minimum viable product (MVP), and which goals can be set aside as stretch goals - features that will make a working app even more awesome in future iterations.

Project Decomposition¶

Now you are ready to make an ordered list of all the tasks needed to fulfill these user and developer stories.

Project Set Up¶

1. Create a git repository with a simple README for the project and clone it down to your machine.
2. Add HTML, CSS, and JavaScript files to the project (e.g., index.html, styles.css, script.js).
3. Create the boilerplate for the HTML file and link the CSS and JavaScript files in the HTML file.

HTML Set Up¶

4. Create a basic HTML structure with a container for the quote and author, and a button.
5. Create a container element (e.g., ) to hold the quote and author
6. Add an element (e.g., ) to display the quote text
7. Add an element (e.g., ) to display the author name
8. Create a button element to trigger the quote generation

CSS Set Up¶

9. Create a basic layout for your HTML elements
10. Styles for the container element for the quote and author
11. Style the quote text and author elements (e.g., font, size, color)
12. Style the button element (e.g., background color, hover effect)

JavaScript Set Up¶

13. Define an array of quote objects, where each object contains the quote text and author. Add three quotes to this structure to start with
14. We will want to select a random quote from our array of quotes, so we will need to write a function to generate a random index number
15. Write a function to select the quote and author based on the random index
16. Write a function to display the quote and author to the DOM
17. Write an event-handler for the button so a new quote is selected when it is clicked.
18. Add an event listener to the button to call the quote generation function when clicked

Now, go back through your User and Developer Stories, and make sure that they are all accounted for. For example, as I was reading through the User stories, I noticed that this one was not yet accounted for:

• As a user, I want to see a different quote and author each time I click the button to generate a new quote.

How will we check to make sure the quote generated is new, and not the same as the last one? I will need to store the last used index number, and if the new index generated is the same, then the function that randomly selects a number needs to run again, until it generates a new index number.

Given this, I will need to add the following to step 14 of the JavaScript set up:

14. We will want to select a random quote from our array of quotes, so we will need to write a function to generate a random index number.

• 14a. Create a global variable to store the selected index number (so that we can check against it the next time we want a new quote), and set it to undefined initially.
• 14b. write a function to generate a random index number.
• 14c. Write a function that checks the random number against the previous number. If it is repeated, it needs to call the number generation function again.

Okay, now we are ready for the last step,

Writing Pseudo-Code¶

Transpose your list above to the JavaScript file as comments

// 13. Define an array of quote objects, where each object contains the quote text and author. Add three quotes to this structure to start with
 
 
// 14a. Create a global variable to store the selected index number (so that we can check against it the next time we want a new quote), and set it to undefined initially. 
 
// 14b. Write a function to generate a random index number. 
 
// 14c. Write a function that checks the random number against the previous number. If it is repeated, it needs to call the numebr generation function again.
 
 
// 15. Write a function to select the quote and author based on the random index
 
// 16. Write a function to display the quote and author to the DOM
 
// 17. Write an event-handler for the button so a new quote is selected when it is clicked.
 
// 18. Add an event listener to the button to call the quote generation function when clicked
 

Now you are ready to put in some test data for your quotes and function stubs:

// Define an array of quote objects, where each object contains the quote text and author. Add three quotes to this structure to start with. I had ChatGPT generate this for me, for testing purposes. I can always come back and add my own quotes and everything should work the same. 
const quotes = [
  {
    quote: "The greatest glory in living lies not in never falling, but in rising every time we fall.",
    author: "Nelson Mandela"
  },
  {
    quote: "The way to get started is to quit talking and begin doing.",
    author: "Walt Disney"
  },
  {
    quote: "Your time is limited, don't waste it living someone else's life. Don't be trapped by dogma – which is living with the results of other people's thinking.",
    author: "Steve Jobs"
  }
];
 
 
// Initialize previous index to null
let prevIndex = null;
 
// Generate random index number
function getRandomIndex() {
  //Generate and return a random index number between 0 and the array length -1 
}
 
// Check if the random index is unique
function getUniqueRandomIndex() {
  //TODO: Call getRandomIndex() to get and index number and check it against previousIndex. If the random index number is the same as the previous index number, re-generate that number, otherwise return it
  
}
 
// Select the quote and author based on the index
function selectQuote() {
  //TODO: Call getUniqueRandomIndex() to get unique index number to select and return a new quote from our array of quotes
}
 
// Get DOM elements - this was not in our pseudo-code list, but we can now see that we will need this to interact with the HTML elements
const quoteElement = document.getElementById('quote'); //TODO: Add this id to the HTML elements
const authorElement = document.getElementById('author');//TODO: Add this id to the HTML elements
const newQuoteButton = document.getElementById('newQuoteButton');//TODO: Add this id to the HTML elements
 
// Display the quote and author to the DOM
function displayQuote() {
  //TODO: Call the selectQuote() function to get a new quote then add it to the DOM
}
 
// Event handler for the "New Quote" button click
function handleNewQuoteClick() {
  // TODO: When the button is clicked, call displayQuote() above to get a new quote to the DOM. 
  // Notice that handleNewQuoteClick() calls displayQuote(), displayQuote() calls selectQuote(), selectQuote() calls getUniqueRandomIndex(), and getUniqueRandomIndex() calls getRandomIndex(). All the functionality is chained linearly. You can easily sketch it out on a piece of paper, if you can't quite wrap your head around it yet.
}
 
// Attach event listener to the "New Quote" button
newQuoteButton.addEventListener('click', handleNewQuoteClick);
 
// Display the initial quote
handleNewQuoteClick(); //This function call starts-off the entire chain of function calls. This is known as the entry point.

Narration of the Program Logic¶

You should now be able to narrate exactly what happens: The user goes to the page and it loads. The HTML, then the CSS, then the JS loads. The JS loads and all the way at the bottom it gets to handleNewQuoteClick() the program's entry point.

This handleNewQuoteClick() function calls displayQuote(), displayQuote() calls selectQuote(), selectQuote() calls getUniqueRandomIndex(), and getUniqueRandomIndex() calls getRandomIndex().

With getRandomIndex() at the end of the logic chain, we now move back through forwards: We get that random index number, we check to make sure it is not same as the previous one, it is used to select a quote from the array of quotes, the quote is passed to the function in charge of inserting the quote into the DOM, whereupon the quote is displayed for the user to see it.

From here, the logic of your program is clear, and you have function stubs written. Now is the time to write the code for each function, focusing on that one small task at a time. (Each function should have exactly and only one job to do!) You may still need to figure out some details from here -- this process need not be perfectly executed for it to be helpful. Hopefully, all the planning has paid off because you know exactly what you need your code to do. The logic solid, you can begin to write the code with confidence.

The more work you do upfront, the easier the coding will be. This is a long process, I know, but after you have taken the time to do it the long way a few times, you'll internalize it and be able to step through it more efficiently.

Think of making a sandwich - once you learned how it's done, you don't have to think about all the steps one by one, but can smoothly run through the steps to get the desired outcome.