"

3 Function Design Recipe: Alt Text Generation (part 1)

Alisha Hasan and Rutwa Engineer

Overview

This module aims to teach you the fundamentals of the function design recipe through an accessibility-centered pedagogical lens. You will explore function design by creating and examining functions with a focus on accessibility. You will learn to consider accessibility in your design process, understanding the limitations of current functions and identifying potential improvements.

Learning Objectives

By the end of this module, you will be able to:

  • Understand and articulate the components of the function design recipe: purpose, examples, header, description of arguments, function body, and tests.
  • Apply the function design recipe to write clear, well-documented, effective functions.
  • Write functions that incorporate accessibility features.
  • Utilize Web Content Accessibility Guidelines (WCAG) to inform the design and implementation of functions.
  • Reflect on the ethical implications of accessibility in function design.

 

The Function Design Recipe

In this section, we delve into a systematic approach to designing functions, which is a foundational skill in programming. This recipe will guide you through the essential steps of function design.

Why Use the Function Design Recipe?

The Function Design Recipe (FDR) helps you break down complex programming problems into manageable parts, ensuring that your functions are well-defined, tested, and easy to understand. This approach not only improves the quality of your code, but also makes collaboration and software debugging much more straightforward for everyone involved.

What is the Function Design Recipe?

Let’s consider the following example problem: write a function that outputs whether or not a number is greater than 50. We’ll use this example to illustrate each step of the Function Design Recipe.

Write example uses.

Choose a name for the function – typically a verb or verb phrase. If you’re struggling, think about how you’d describe the function’s purpose in 2-3 words.

For our function, we’ll choose is_high_contrast(), which tells us whether or not the luminance (light intensity) difference between two colours is sufficient for high contrast. This is important when determining how readable text is. The luminance of a colour is a value between 0.0 and 1.0, with 0.0 representing no light emitted (black) and 1.0 representing the maximum light emitted (white). As a basis for determination, the difference between two colours that are sufficiently high contrast and readable against each other should be greater than 0.5. We provide two examples of the function’s usage and expected output, covering typical input cases. These examples should be placed inside a triple-quoted string (“””) and indented as part of the docstring. Here’s what we have so far:

   """
   >>> is_high_contrast(1.0, 0.0)
   True 
   >>> is_high_contrast(0.8, 0.7)
   False
   """

As we can see, white (luminance = 1.0) and black (luminance = 0.0) are high contrast, but colours with a luminance of 0.8 and 0.7 respectively are not.

Write the function header.

Write the function header above the docstring. It should include the names of the parameters, the object type of each parameter, and the return value.

def is_high_contrast(lum1: float, lum2: float) -> bool:   
   """
   >>> is_high_contrast(1.0, 0.0)
   True 
   >>> is_high_contrast(0.8, 0.7)
   False
   """

Write the function description.

At the start of the docstring, add a description of what the function does. Ideally, mention each parameter by name; the goal otherwise is to make sure the purpose of each parameter is clear. Describe the return value as well.

def is_high_contrast(lum1: float, lum2: float) -> bool: 
   """
   Check if the contrast between two luminance values is high enough.

   Parameters:
   lum1: The luminance value of the first colour. (0.0 to 1.0)
   lum2: The luminance value of the second colour (0.0 to 1.0)

   Returns: 
   bool: True if the contrast is sufficient, False otherwise.
   >>> is_high_contrast(1.0, 0.0)
   True 
   >>> is_high_contrast(0.8, 0.7)
   False
   """

Implement the function body.

Implement the function. Ensure the indentation of the implementation matches that of the docstring. You may find it useful here to come up with some more example calls for yourself when figuring out how to implement the function.

def is_high_contrast(lum1: float, lum2: float) -> bool: 
   """
   Check if the contrast between two luminance values is high enough.

   Parameters:
   lum1: The luminance value of the first colour. (0.0 to 1.0)
   lum2: The luminance value of the second colour (0.0 to 1.0)

   Returns: 
   bool: True if the contrast is sufficient, False otherwise.
   >>> is_high_contrast(1.0, 0.0)
   True 
   >>> is_high_contrast(0.8, 0.7)
   False
   """
   return abs(lum1 - lum2) > 0.5; # simple threshold for contrast

Test the function.

Test your function on all your example cases as well as any additional ones you created during the implementation process. Add some cases of edge cases to ensure your implementation accounts for those as well.

In the event that you encounter any failed test cases, first ensure that your tests take the correct input and expect the correct output. Then, go back to your implementation and try to identify and fix any possible issues in the code. This process is called debugging your code, and will be useful for you in every one of your programming endeavours.

Now that you’re familiar with the FDR, it’s time to tackle your first case study and real application of a function that attempts to follow it.

Case Study – Alt Text

What is Alternative (Alt) Text? Alt text is a brief description of an image used in HTML code to ensure images are accessible to users who are visually impaired. Screen readers use alt text to describe images to users, allowing them to understand the content and context of the images.

Web Content Accessibility Guidelines (WCAG):

The Web Content Accessibility Guidelines (WCAG) provide recommendations to make web content more accessible. Here are key principles related to alt text:

  • Perceivable: For alt text, this means providing text descriptions for images and other non-text content.
  • Operable: For images, this means making sure screen readers can explain the content and context of an image.
  • Understandable:  Alt text should be clear and concise to describe the image’s purpose effectively.
  • Robust: Content should be created in a way that can be easily understood and used by different tools, including those that help people with disabilities.

Example of helpful alt text: 

For an image of a beach – “A sunny beach with palm trees and clear blue water.”

Example of vague alt text: 

For an image of a beach – “Image of beach.”

Notice how the alt text that was more helpful was more descriptive of elements in the image? The purpose is to allow users with varying degrees of vision impairment to get a sense of what the image contains through a detailed description of it.

Your Task:

Consider the following Python function that generates alt text for images based on a given description and answer the following questions:

def generate_alt_text(description: str) -> str:
   """
   Generate alt text based on the given description.

   Parameters:
   description: A brief description of the image.
   >>> generate_alt_text("a sunny beach with palm trees and clear blue water")
   'An image of a sunny beach with palm trees and clear blue water.'
   >>> generate_alt_text("a beach")
   'An image of a beach.'
   """
   return "An image of " + description + "."
  1. Given the examples provided in the function’s docstring, which alt text would provide a better experience for a visually impaired user? Why?
  2. Rewrite the alt text for a different image, such as “Image of a city skyline,” to be more descriptive.
  3. Why is it important to include specific elements (like “palm trees” and “clear blue water”) in the alt text for an image of a beach?

 

Test Your Knowledge

 

References

License

Function Design Recipe: Alt Text Generation (part 1) Copyright © by Alisha Hasan and Rutwa Engineer. All Rights Reserved.

Share This Book