DEV Community: Jean Paul

Developer Weekly Blog #4 - Playwright

Jean Paul — Wed, 29 Nov 2023 15:01:37 +0000

Introduction

This week I learned about Playwright, this is a tool to do different types of testing like: automating testing or visual testing on your web applications. What I like about this library is that it needs almost 0 configuration and you already have a lot of tools ready out of the box to create your tests, like a tool that helps you to create your own tests called codegen, when you initiate your project automatically create a pipeline that is easy to use in your pipeline, it allows you to create visual tests for your app and you’re able to run the tests in various browsers. And using this tool I realized that this was an ideal solution for a problem that I had back in the past and I want to share this experience with you.

I was writing tests on React Testing Library, a tool to create unit tests for components. At some point I abused this tool, using it in moments where I shouldn’t, creating long tests, those tests started to become flaky tests (tests that sometimes succeed or failed with no changes on the code.) Why were they failing may ask yourself? Because due to how it works this tool, it emulates a browser and sometimes as we were refreshing so many things a lot of times happened that doesn’t reach to the point where the changes were reflected on the emulated browser and the test failed.

It would be nice back then to have the possibility to write some tests in Playwright because they would be more effective and accurate than my long and ineffective tests written in Testing Library. But this is not the only reason that I would recommend to use it on your projects, also is easy to use, has a lot of ways to debug your tests, it has a tool that helps you to create your own tests called codegen, is easy to deploy, you can create visual testing and you’re able to use it in various browsers. Now that I list you some of the reasons why I love this tool it’s time to see how it works.

Why is important to include automating testing

Automating testing is so important in your workflow because this allows you to make changes with the confidence that this doesn’t break anything extremely important on your app. Have you ever made a change and feel the stress and anxiety of something breaking? So where does this insecurity come from? I think more than impostor syndrome as an answer, is that it is not always possible to check all the scenarios where your change is going to be reflected. And it is impossible that your app works fine in every case, but you’re able to make your app work fine most of the time. But how to ensure nothing breaks?

You possibly can test every time you make a change but a good way to ensure repetitiveness is through automated testing. And to better understand the benefits of doing it I refer to the story of Google Web Server that illustrates how automated testing improves productivity confidence on changes and the reduction of numerous bugs. Using this practice you ensure the changes don't break some important behavior, reduce stress, reduce uncertainty, keep application flexible and easy to change overtime and increase confidence on your team. When the test succeeds you deploy with confidence.

So I want to share information about this tool that allows you to write this kind of test in an easy way with low configuration.

Getting started with Playwright

To install Playwright you need to have Node 16+ installed, and get Playwright through the command $npx playwright install this will get the browsers to run your tests (Chromium, Mozilla and Safari). After that you’re able to use the commands that Playwright includes to run your tests and complementary tools to create your tests. If you want to add the configuration to an existing project use $npm init plawright this creates some files in your project but the most important is playwright.config.ts that allows you to change the default configuration and indicates that Playwright is being used in this project. From there it is just a matter of creating your tests, to do it create files with the extension .spec.ts on the test folder and run them with $npx playwright test. And see the results with $npx playwright show-report. With those steps you’re ready to create more tests in your existing project. Let's see what it is like to create a test.

The first thing you need to take into account is that you're using a real browser. If you're familiar with other UI testing libraries, you'll find a lot of similarities between them. However, since you're using a browser, there are some functions like changing accessing a different URL, something not available in other UI testing libraries like React Testing Library. With that in mind, how does a test in Playwright looks? A test in Playwright is mostly composed of 3 main instructions: goto(), locator(), and expect() throughout a test. So let's define the purpose of each one of these:

goto() is a function used to navigate to a website, similar to typing a URL in your browser. This instruction is used to access the page that you will be probing.
locator() is used to find elements within a website. Playwright uses the same syntax as CSS selectors when using the locator method. This means that you can find elements using HTML element types, classes, or IDs to identify them. There are other ways to locate elements, but they are more related to accessibility attributes rather than HTML properties.
expect() is used to compare the actual results of a test with the expected results. This function allows you to check if elements satisfy certain conditions, such as being visible, checked (for checkboxes), or having specific properties. There are many possibilities for comparing the results with the expected results. I will explain some of the most common methods to make these comparisons.

So I want to show a brief example that shows a short a test to add products in a shopping cart on a website called automation exercise, designed to train yourself to make automated testing.

import { test, expect } from "@playwright/test";

test("Shopping cart test", async ({ page }) => {
  // Enter to automationexercise.com webpage
  await page.goto("https://automationexercise.com/");

  // Locate link to access the product 
  await page.locator(".features_items .choose a").first().click();

  // Click to skip ads 
  await page.mouse.click(0, 0);

  // Add 3 products
  await page.locator("#quantity").fill("3");

  // Add product to the cart
  await page.locator(".product-information button").click();

  // Click on the button to close the modal and keep navigating 
  await page.locator(".modal button").click();

  // Expect the modal is closed once is clicked 
  await expect(page.locator(".modal")).not.toBeVisible();
});

This is the step-by-step process of what I'm doing here:

Enter the website automation exercise.
Go to the section that includes the products and find the first link located there.
Add an instruction to skip the ads that sometimes appear on the website and click in the top-left corner to close a modal that contains the advertisement.
Once on the product detail screen, fill out the form to add 3 products.
Click the button to add the products to the basket. When the products are added, a modal is displayed.
Close the modal by clicking the button to do so.
Close the modal using the button inside, and finally, check if the modal is not visible.

If you notice that I was on two screens while doing this test, do I need to explicitly mention it? No, because Playwright does a lot of auto-waiting for me. For example, when moving to a new URL or waiting for the modal to close. Those are the tiny details that makes the developer experience awesome using it.

How to wait for something to happens

But if you want to wait for something to happen because sometimes you need to wait for something to continue your test, like wait for some element to appear/disappear on the screen. You have the option to do it explicitly using waitFor() to make a pause until some element satisfies a condition. I think this is a very repetitive situation when using a testing framework for the UI. In my first experiments I have to use it to wait that an elements appear on the screen and I wanted to share with you an example about how I use it.

This is a test that need to wait for an element to be visible to continue to test a functionality.

test("Search for something that has at least one result", async ({
  page,
}) => {
    // Enter to Playwright page
    await page.goto("https://playwright.dev/");

    // Find the search button
  await page.getByRole("button", { name: "Search " }).click();

    // Locate the search box to find a doc
  const searchBox = page.getByPlaceholder("Search docs");

    // Click on the search box
  await searchBox.click();

  // Type havetext on the searchbox
  await page.getByPlaceholder("Search docs").fill("havetext");

  // Wait for one result to appear on the screen
  await page
    .locator(".DocSearch-Dropdown-Container section")
    .nth(1)
    .waitFor({ state: "visible" });

  // Count how many results does it get
  const numberOfResults = await page
    .locator(".DocSearch-Dropdown-Container section")
    .count();

    // Expect at least to have one result 
        // looking at the results section
  await expect(numberOfResults).toBeGreaterThan(0);
});

The step-by-step process is something like this:

Go to the Playwright website.
Find the search button.
Locate the input with the placeholder "search docs".
Click on that input.
Fill the input with the text "havetext".
Wait for the results to be visible because we need to wait until the result is sent back to us.
Count the number of results.
Make sure that at least one result exists.

Now that we are familiar with the most common tests you will find, let's talk about the tools that come with Playwright.

Tools

One of the things I love the most about Playwright is the tooling that comes with it. There are a lot of different ways that Playwright facilitates the job of creating or fixing tests. Let's begin with the main tool that I found very useful to get started with: codegen, a tool that opens a browser and starts to create code based on the actions you perform on the website, such as clicking on an element, typing in a form, or selecting text on the page. Is it possible to use the codegen result as the tests you will use? Sometimes yes, but I think for the vast majority of the tests, you will need to make some changes to improve things like the locator of an element, use a REGEX to ignore case when searching for text on your website, or make any other improvements to increase flexibility in your tests. Now let’s talk about debugging tools.

To debug in Playwright, there are plenty of options to see the steps it's executing. For example, if you want to observe how the tests execute in the browser, you can do so by adding the --headed flag when running the test. However, the test might be fast, and you may not perceive anything. If you prefer a slower execution, you can use an option called slowMo to prevent the test from executing too quickly. Additionally, using the --debug flag opens another window that allows you to pause, proceed to the next step, or run the test until the end, giving you control over the test's actions. These tools make your life easier when you need to fix errors, and these are not the only options available. Another option is called "trace."

When you run your test with the flag --trace on, this will record every activity that the browser does. After the tests are done, the failed tests will generate an interactive record that allows you to see how the element was located and how the DOM looks at that moment. It's similar to when you open a page with DevTools, which allows you to interact with the page and view the details. To see the trace, you need to use show-report to see the test results and be able to open the trace. The report is only available through the option show-report. You cannot serve it through other static servers or open it as plain HTML, especially when there are files that you need to view, like the traces so if you want to see traces results use that option.

Now we are going to review the functions available to write tests and let’s begging with the selectors.

Selectors

There are many ways to filter elements inside a page, and now I want you to become familiar with some of the ways to find elements inside a page. You can find elements by HTML attributes or the purpose on the page, such as accessibility role, label text, placeholder (if it is an input), text inside a page, alt text of an image, title attribute, or test ID. To find elements using any of these criteria, use some of the functions provided by Playwright.

getByRole() to locate elements based on how people that uses assistive technologies perceive the page, so is useful to review which accessible roles exists to help you to understand which type of elements are you able to locate you can find more about roles in the following link: WAI-ARIA Roles MDN Web Docs.
getByLabel() to locate mainly form related elements, the label is the inscription for any type of input like text , checkboxes, radio buttons, selector and many others.
getByPlaceholder() is related to form elements as well, but it is created to find elements based on a text that indicates how to fill the input or what the input is for.
getByText() to locate any text inside of the page.
getByAltText() helps you locate an image using the descriptive text used by people who use assistive technologies to understand the content of those images.
getByTitle() to locate elements that use title tag
getByTestId() is a special attribute used in HTML called test-id, which is intended for testing frameworks to easily locate elements on the page.

If you want to get an extensive list of all the selectors and get more information, go to the official documentation on locators to learn more. Since there are many ways to locate elements on the page, there are also many ways to compare final results with expected results, so let’s review some of them.

Assertions

There are many functions to compare results, so I want to talk about the most common ones that you will use to check if some element of the page satisfies a certain condition. Let's see some of them:

toBeTruthy() checks if an element is not false, null, undefined, or 0. It is used to verify if a condition is met and is one of the simplest ways to compare if an element fulfills a certain requirement. The opposite is toBeFalsy(), which checks if something does not meet a condition.
toBe() checks if the value is the same. It is one of the most basic ways to check if something has an expected value. For example, when performing a search, you expect to have a certain number of elements.
toBeDefined() checks if an element is not undefined. It is useful for verifying the existence of an element on a web page. For example, you can use it to check if a button is present on the web page.
toBeVisible() checks if an element is visible on the web page. For example, if you have an element that appears or disappears depending on user interactions, you can use this function to check if the element is visible on the page.
toHaveText() check if some element have some text. Let’s say a button and you need to verify if the call to action have the right text, you can use this function to verify it.
toBeDisabled() helps you verify if an element is disabled. It is useful to check if buttons, inputs, and any other kind of interactive element are not enabled for the user to interact with.
toHaveURL() checks if a link has the correct URL. When you need to verify that a link has the correct redirection, you will use this.
toHaveAttribute() allows you to select an attribute and compare if it contains a certain value. For example, if you want to check if an image has a specific width. And not only that, you can virtually compare any attribute that was not previously included.

Sometimes, we actually need to verify that something does not satisfy a condition. To cover those cases, we have the .not attribute available. It allows us to check if something does not match a condition. For example, if you want to verify that some text has changed, you can use the .not attribute to check if the text is no longer on the page.

I will probably continue to describe every way to make an assertion, but you can check every assertion that exists in the test assertions documentation and you'll get more information there. If you consider that you need to use toHaveAttribute() to compare something, please first read if there exists a method for that because it will make your intention clearer.

Now we talk about one of the most impressive features, that is doing visual testing with Playwright.

Visual testing

Have you ever imagined having the chance to visually compare how a page looks before and after a change, automatically, and know if any differences exist? Well, this is now possible with Playwright. You can create a screenshot that automatically compares the appearance before and after running tests. If any differences are found, the test will fail. The best part is that these tests generate a diff file that shows the specific differences between the previous and new versions, allowing you to easily spot the changes.

To create this kind of test, all you need to do is use the assertion toHaveScreenshot(). Once you use it, it creates an image that will be used as a reference for how the page is supposed to look, and it compares the results with that reference every time the test is executed. If you feel this is too strict and want to allow a little freedom, you can define a tolerance for the difference between screenshots using the option maxDiffPixels. This allows you to change the maximum tolerated difference in pixels between two images.

So doing a visual testing is that simple as write a test like this:

test('example test', async ({ page }) => {
  await page.goto('https://playwright.dev');
  await expect(page).toHaveScreenshot({ maxDiffPixels: 100 });
});

And you got it you have your visual test online.

Final thoughts

I found Playwright to be a tool that is really easy to use. It has a lot of capabilities out of the box. If you're familiar with other tools for UI testing, this will be familiar to you. Remember that automated tests are a way to increase confidence in your app in a scalable way. You can add a few tests on Playwright to make sure that the most important parts of your app are working fine. If you have an e-commerce test where you can log in, add products to your shopping cart, and complete the purchase, it will cover one of the most common and important flows in e-commerce applications.

Take advantage of this tool and test it because it will increase your productivity overall and catch bugs early on the development.

Developer Weekly Blog #3 - Web Accessibility

Jean Paul — Mon, 30 Oct 2023 22:26:38 +0000

This week I was studying accessibility on the web. There are a lot of lessons that I take about a course that I take about the topic. To summarized what I learned what do you need to check in order to have good accessibility is to assure you include in your web or component is:

The usage of semantic HTML in your tags
Guarantee a similar experience with screen-readers and how the people use it
Have a good contrast with your text in order to be easy to read it
Guarantee that the focusable sequence between elements makes sense and is similar as the default experience
Use LightHouse to measure and get further accessibility improvements

Using these key points you will guarantee a good experience for all kinds of people in your website and these will get you extra points at the SEO(Search Engine Optimization) because it indicates the meaning of the content on the page. So let’s dive deep into each of these points.

Usage of semantic HTML in your tags

When we are writing HTML we have the freedom to write in whatever way we want to make it, but using the tags introduced by HTML 5 we have the opportunity to correctly label some common parts of our website like the header, the navigation bar or the footer. Using them allows a blind person, for example, that is not able to see the page to get more information about where he is located at the moment and give more valuable information. Take into account this two examples:

<p> Steps to make a toast </p>
<p> Take out your bread </p>
<p> Turn on your stove </p>
<p> Put the pan </p> 
<p> Put the bread into the pan </p> 
<p> Wait 2 to 5 minutes </p>
<p> Remove the bread </p>

When some screen-reader goes through this text will read something like: “paragraph steps to make a toast, paragraph take out your bread, paragraph, turn on your stove” but this is more like a step by step tutorial, it would be better if you use a list to describe it, something like this:

<p> Steps to make a toast </p>
<ol>
  <li>Take out your bread</li>
  <li>Turn on your stove </li> 
  <li>Put the pan </li> 
  <li>Put the bread into the pan</li> 
  <li>Wait 2 to 5 minutes </li> 
  <li>Remove the bread</li> 
</ol>

With the same text, a screen-reader now we can go something like this: “paragraph steps to make a toast, ordered list, first take out your bread, second turn on your stove” this will make more sense to the user that is reading the content with this assistance. But this not only applies with content related to text, you also need it to take into account at the moment of creating the layout of the page and use the appropriate tags.

If you want to create a header, don’t use the generic with a class <div class="header" > prefer to use the header tag <header> so for the user it is clearer where they are standing. There are around 100 semantic elements but you can start with the basics on how to create a basic layout with these tags: <header>, <nav>, <section>, <article>, <aside> and <footer>. To start creating understanding on how to structure a complete page.

Guarantee similar experience with screen-readers

When navigating on our page it is common to have hidden elements, when you hide elements you are thinking in hiding it just visually and neglect that you need to hide it as well for people that don’t operate the website in the same way as the rest. In order to hide it you need to use ARIA (Accessible Rich Internet Applications) attributes, those are HTML attributes devoted to accessibility that indicates the state or give more information about an element, there are a lot of attributes that you are able to use, if you want to look a more complete list you can look at the documentation in MDN about ARIA states and properties.

In this case where we want to hide an element apart from hiding from the screen we need to use aria-hidden and this attribute receive a boolean value so you need to use it in this way <div class="card" aria-hidden="true" /> so this element is skipped by the reading sequence of assistive technologies.

But other scenario where you can use it is to give more information to the user about what is about this part of the page you can use something like aria-label and aria-description to indicate an user what is this part about, if you have a carousel about the products that you are selling, you can use these tags to give more context about where they are navigating.

<div 
  aria-label="carrusel"
  aria-description="List of the best selling products"
>
    <!-- ... --> 
</div>

Adding more information and helping to guide a larger audience will make your application easy to use for them. The best way to guarantee a similar experience is to get the basics to navigate with a screen-reader and navigate through your app and see if there is a similar experience with what you see with the way you are navigating with the screen-reader technology.

If you never used a screen-reader before you can start using it in Windows and Mac, in Windows there is a pre-installed program called narrator that you can turn on and off using the shortcut Windows logo key + Ctrl + Enter if you want more information you can access the official documentation here. In Mac exist voice over

Have a good contrast in your text

Sometimes we want to be super creative with the colors of our website and we forget to make the texts readable and the texts are super important because it is the main content that you see when you enter a website. Could you imagine how the app of your bank would look like without the text? Or how would the app that allows you to buy a ticket for a flight look like? It would look really confusing without the text.

So in order to help the people that go to the website include good contrast in your text and to do it you can use a metric called contrast ratio. This number indicates how much difference exists between the background and text. If you want to check this number you can use this tool: color contrast checker to be able to know this number, you can start with a minimum of 4 of contrast, but if you want to be really great you need a contrast ratio of 7.

As you see, texts are important so take care of them in order to guide the people that come to your website.

Guarantee that the focusable sequence between elements makes sense and is similar as the default experience

Yeah this is a long title but I didn’t come up with an idea that expresses those two things at the same time. Sadly most of evaluation of something to be accessible is a manual process, this is the reason that if you want to become great in accessibility you need to be able to use some screen reader or be able to navigate a website with just your keyboard because in that way you are able to verify by yourself if the experience is the same across different type of people.

For example, modals, this is a polemic component to get done well, one of the aspects that could go wrong is this: have you ever encountered a modal that does not have a close button? Or worse yet the button is so tiny that it is almost impossible to click on it? Now imagine how the experience is for the people that are not able to see a screen and do not have a button to close the modal. For them not having a closing button would make it more difficult to navigate in that kind of website.

And the same applies for elements that are not visible, when something is out of the screen or shouldn’t be visible there is an attribute that you can use in order to hide it called aria-hidden, if you have an element in the page but is not displaying at the moment use this property to help other type of users to skip that content, that would make them more satisfied with the navigation of your website.

Use LightHouse to measure and get further accessibility improvements

If You Can’t Measure It, You Can’t Improve It, this is the basis of any quality control management so be pragmatic with this matter and use a tool like LightHouse that helps you with puntual suggestions that make the experience for any type of user better. If you know about another tool I’m open to hear it.

So leverage from the existing tools, if you have an project use a static analyzer in order to prevent earlier any problem with the HTML of your website, you can check on this plugin that you can add to your linter called eslint plugin JSX a11y for React that help you at detect those errors. For other libraries or frameworks you can check this accessibility list of linters.

Last thoughts

For me studying about accessibility help me to understand better how other people are able to use this websites, this features were added to help people with some kind of limitation like someone blind but this improvements shouldn’t apply only to them, imagine if you have some kind of problem with your mouse and now you are only able to use a website with your keyboard or think about how difficult some programs were difficult to use just because the text has small fonts or low contrast. So this is not only for this kind of person, it is to help out a larger range of people that you don’t know how this is going to impact.

In general, thinking of different types of people using your product will help you to reach a broader audience.

Developer Weekly Blog #2 - Documentation

Jean Paul — Thu, 12 Oct 2023 16:01:59 +0000

Introduction

This week I was working in my talk that is going to be presented to university students, this week I review the topic about documentation on the book software engineering at Google, also I assisted to the first Pioneras Conf in my city Medellin, this Conf was targeted to girls that want to start their careers in tech, there was a great attendance and come people from everywhere, PionerasDev is an NGO in my city that aims to include more women in tech and help growing their careers, definitely check on that it’s an impressive initiative. Maybe in future entries I include some of the topics that I learned at the Conf.

This week I’m going to talk about documentation. How to manage? How to write? Why is it important? What type of public read documentation? What type of policies do you need to include to manage documentation? So let’s get started.

Documentation

Documentation is a serious topic that nobody wants to speak about, most of the engineers hate to do this task the have many reasons for this like: the extra effort in writing about the code, engineers tend to think that they are not capable of writing good documentation or think that writing as a different skill to acquire. But we should insist on increasing the amount of documentation and the way to accomplish that is to take documentation seriously.

The way to make documentation serious is to treat it like code, this means to create tasks related to documentation, making pair reviews, create a version history and prioritize on your sprints. It sounds like a lot of work but this is an investment that will pay over time, there are many benefits when you write it: helps you to remember what the code was about in the first place, reduce questions when someone else read it, force you to think if the code makes sense and signals that is a professional codebase and well maintained. Once the culture of writing documentation is established more people will get into it. So the next question is: how do we write good docs?

How to write documentation

When writing you should always ask yourself: for who I am writing for? The number one mistake when we are writing is to think from our perspective and doing so makes the text biased towards our own perspective, we consider that everyone shares our context but they do not. For this reason it is always recommended to make a pair review (like code) so you guarantee that other people are also able to understand what you write.

“Optimize for the reader”
Software Engineering at Google

If you do not know where to start is a good idea to make these questions in order to get understanding the context of your topic:

Why were these design decisions made?
Why did we implement this code in this manner?
Why did I implement this code in this manner? And imagine you’re looking to your code two years later

So when writing the documentation on your code, focus on the questions: what does this code do? And why was it implemented in that way? Those are the common questions a future reader will have when reading the code. But if you want to go deeper you can ask yourself more questions to get more information.

There are common questions that help you to include all the possible information around a topic, I am referring to the 5 w’s and h, these questions are: what? why? when? Who? where? And how? Asking this questions helps you to gather information on any topic, for example you can ask yourself the following questions:

What is this doc for?
When was created?
Who is going to read this?
Where does the doc be saved?
Why does this document exist?

With those questions answered you are able to check if your documentation is precise and have all of the information needed to make it. But until this moment we didn’t ask ourselves about what kind of readers exist. So let's see what kind of readers we can encounter using our documentation.

Types of audience

There are different types of audience depending on the level of engagement in the project. We can classify people in 3 types and we’re going to imagine who is these people if you were creating a library:

People working on the code: these people are programmers related to the project and are experts in the programming language. In your library they would be the maintainers of the library.
Consumers: people related with the functions that the code or the API provides and only consume what is there. They are the people who download your library and use it in their code.
Specific task: people that are looking for how to accomplish a task. They are the people that don't want to go deep in your library but need it to do some specific task.

Keeping in mind for who you writing for helps you to focus what are the topics you need to write about, because consumers of a library doesn’t want to know the specifics about how you implement a thing, but for a maintainer want to go deep in the specifics because maybe that helps them to fix something in the future, meanwhile for the people who wants to do something specific just need to find how to do their task. And you need not only to consider the level of engagement also the way they are searching information.

The searchers navigating your content could be classified by two types:

Seekers: this is the kind of people who know what they want. To help them to get what they want quickly, give them a good structure easy to scan through the document
Stumblers: they don’t know what they want. To help them, give it a summary at the start or the end of the document to know what the document is about

Giving a good structure and summarizing your docs help to different kinds of people to be guided through the document. But you think that only comments on your code are the only documentation needed? There are many types of documents that you are able to include in your projects.

Types of documentation

There is more documentation than just commenting your code and we are going to explore what other kinds of other documents you could include inside your project. We could say that there are these types of documentation: code comments, design docs, tutorials, conceptual documentation and landing pages. Let’s see each one of them.

Code comments

This is what pops out of our mind when we think about documentation, this is the most fundamental way to document and it is a good idea to include these activities into our workflow to improve maintainability over time. A lot of programming languages had their own syntax to create documentation that facilitates this job. For example JavaScript has JSDocs and Python has PyDoc to document. Getting to know how it works those standards is beneficial to you and your team to use it and read it properly.

And what to include in our code documentation? The question is a little bit uncomfortable, you can consider asking yourself the following questions to write about: what does this code do? What was the reason to create this function, class or whatever? What is the expected result? What is the main use case or use cases to use this? What does this module include? What are the edge cases? Depending on the type you are describing it is nice to have some things, for example classes it is beneficial to write about the purpose of the class and important methods of the class. Functions should start with a verb because they do something and is a good place to describe parameters, return value and exceptional cases. To see it let’s take a look at an example.

Let’s take as an example this piece of code:

## Maybe include an example of code
class Vehicle: 
  def __init__(self, color, wheels, seats):
    self.color = color
    self.wheels = wheels
    self.seats = seats
    self.speed = 0
    self.is_on = False

  def accelerate(self):
    self.speed += 1

  def brake(self):
    self.speed -= 1

  def start(self):
    self.is_on = True

  def stop(self):
    self.is_on = False

  def paint(self, newColor):
    self.color = newColor

  def __str__(self):
    return f"""{self.color} vehicle with 
               {self.wheels} wheels and 
               {self.seats} seats""""

It’s clear enough but let see how becomes more easy to read with some documentation and put on the perspective of someone that use this module or doesn’t want to know the specifics of your code and the people that will read this code in the future:

class Vehicle:
  """
  Represents a vehicle into the game, the user is able to
  personalize color, wheels and seats. When the user drives 
  is able to change speed and turn on or off the car whenever 
  they want to. 

  In order to change speed of the car you need to `acelerate()` or 
  `brake()` to increment or reduce speed.

  To be able to use the car you are able to use `start()` and when 
  you are done use `turnOff()`. 

  To change color use `paint()` to assign new color. 
  """
  def __init__(self, color, wheels, seats):
    """
    Initializes the vehicle with the given color, wheels and seats.

    color: string - RGB color of the vehicle
    wheels: number - number of wheels of the vehicle 
    seats: number - number of seats of the vehicle
    """
    self.color = color
    self.wheels = wheels
    self.seats = seats
    self.speed = 0
    self.is_on = False

  def accelerate(self):
    """
    Increments the speed of the vehicle by 1.
    """
    self.speed += 1

  def brake(self):
    """
    Reduces the speed of the vehicle by 1.
    """
    self.speed -= 1

  def start(self):
    """
    Turns on the vehicle.
    """
    self.is_on = True

  def turnOff(self):
    """
    Turns off the vehicle.
    """""
    self.is_on = False
    self.is_on = False

  def paint(self, newColor):
    """
    Changes the color of the vehicle to the newColor.

    color: string - RGB color of the vehicle
    """
    self.color = newColor

  def __str__(self):
    """
    Return a text with the description of the vehicle

    Returns: string - a string representation of the vehicle
    """
    return f"""{self.color} vehicle with 
               {self.wheels} wheels and 
               {self.seats} seats"""

If you are not familiar with Python docstrings you can read more here. At the start we include the use case for this piece of code and describe what actions to perform at the definition of the class. In each method we describe what is the action expected, a key here is to describe what is this method doing but don’t explain how, the how is the code. And for functions with a return funciton like the last function we describe what is the return type expected. These comments will help you and others in the future to better understanding.

When you include this as a common practice this increases usability because you indicate what this module does and when someone else is using this, the code editor will tell you what is the goal of each thing. The end result is a larger file but overall it is a great improvement. If you see the first code was not bad but with the documentation it shines and will improve collaboration with the rest of the team.

Design docs

These documents are a good way to create a register about the design decisions and discuss with other engineers, you can think about the design docs like the planes of the building, they describe what we’re going to do without making all the effort on creating the thing. In these texts you are going to talk about the goals of a new project and implementation details, strategies, pros and cons of each strategy and anything you need to take into account. These types of documents are required to start a new project at Google, imagine the importance of these.

So you can consider doing this type of document when you want to start a new project or doing a great effort and you need to think deeply on how to do it. To facilitate things I am going to include a template of the design doc made by @charlieBot a former engineer at Google, that you can check at the design doc template here. Using the template will make easier to start using it.

Conceptual documentation

Sometimes you need to introduce new ideas that are not trivial when someone reads your code. A conceptual documentation could be the key to guide new people to get familiar with new terminology that they don’t know. In this type of documentation you can explain what that concept is about? How to use it? Why was the origin of that? Why is it necessary? And maybe how to facilitate things when using it? This documentation is useful when comments in code are not enough to elaborate certain ideas that go beyond you possible write in a comment.

Tutorials

How-to guides are valuable, the most important guide that you need in your project is how to set up and get started in your project, this way new people are able to start to contribute to your project quickly, this kind of guides are straightforward to write because you need to describe step-by-step what the user should follow.

When write tutorials is good to follow this tips:

Add numbers to each step
Add a new step when user input is required
Clarify if a pre-condition is needed to meet in order to do some step correctly
Give a clear indication of what the user needs to perform at each step
Show what is the expected output
When done with tutorial, try it to verify that the steps execute correctly

Following these guidelines will make it easier to write clear tutorials to end users.

Landing page

A landing page is perfect to organize your information and add navigation to what you document in your project. You need to make this right because maybe it is the first contact with the project for so many people so having a good structure facilitates users to navigate through the information easily. So check that it is easy to navigate through the documentation.

But every documentation comes to an end, let’s see how to deprecate a documentation.

Deprecation of a document

Like software, documentation also has its own life cycle and when documentation is no longer useful you need a way to indicate the end of their life by adding some comment at the top that says: “this not longer works!” and redirect to recent documentation if appropriate. But please don’t let deprecated documentation go freely without people knowing that it is not useful any more.

Useful policies for documentation

The best way to maintain good documentation is to treat documentation like code. So there are some policies that will help you to increase ownership on documentation on your team:

Documentation needs to have version control: in order to have a good control on what you did and to recover something when you need to.
Clear ownership: assign a responsible to maintain a doc. when people are able to give feedback to someone is easy that get fixed when there is a responsible to do it
Do pair review: when a new change is going to be published it is necessary that someone else review the new changes.
Have issues tracked: like a code when a bug appears is registered in your task manager, when something needs to be improved on documentation put it on your task manager and do a follow-up.
Periodically evaluate: time to time review that the documentation is accurate with the information, this is critical for something like set-up tutorial

The main idea is to leverage from the established process to use it with your documentation so it is easy to maintain the workflow and not do an extra process just for documentation.

Final thoughts

I was impressed by one idea of the book that states something like the state of documentation in 2010 was the same as testing in the 1980's, this means poor tooling and almost no worries about this topic. With the implementation of policies mentioned before there was a good improvement at Google but still there is a good improvement margin in this area. For example some new tools are appearing like Storybook for UI components is something fresh that is going to become a standard in all JavaScript projects but I could imagine this is going to happen in other types of similar projects in other languages.

So investing time in integrating better tooling to document is going to make things easier and things like LLM (Large Language Models) like GitHub Copilot will make this tedious task more easy to the developers bringing to them a better experience in the future.

Developer Weekly Blog #1 - Programming vs. Software Engineer

Jean Paul — Mon, 02 Oct 2023 15:18:05 +0000

This week I was reading about software engineering. I'm preparing a talk directed to university students studying this area. So the concept to my talk was directed by a primary question: what is Software Engineering anyways? The concept that I got when I was studying at the university was something like: software engineering it’s something like creating diagrams, trying to satisfy the client (because he doesn’t know what they want,) make a well structured plan and use agile methodologies.

But for the preparation of my new talk I challenged my view to the emphasis on the planning side of a project and try to focus more on the day to day side of things in software engineering that are more trickier to master than just planning an ideal thing that maybe doesn’t see the light.

So I decided to review some literature about the topic. And I found something that fit into what I wanted, a book I already knew, called: Software Engineering at Google. I read two chapters that I selected to prepare my topics, more specifically chapter about what software engineering? and code review, I absolutely love how developed the topics there. First of all that I need to mention about this book, contrary of what you expect this is not a book about rules written in stone, it’s more about a series of essays about topics around daily practices used by Google Engineers in their day to day life.

So this week the main ideas that I gather from my readings are:

Programming vs Software Engineering
Software engineering is programming integrated over time
It’s better to upgrade your codebase in tiny beats than large scale changes
Hyrum’s law: “all observable behaviors on your system will be depended on by somebody”
Think about the trade-offs
Code review it’s one of the more valuable things to guarantee clean and maintainable software
Code review it’s more effective when it’s small (less than 200 lines of code) and most of the time it’s done by one person to be more efficient
Programming it’s an individual effort and software engineering it’s a team effort

So let me explain a little bit about some of them

Programming vs Software Engineering

There is a critical difference that you need to understand explained in the chapter What is software engineering? about programming and software engineering. Programming is an individual effort and software engineering is a team effort. But saying that is something simplistic, there are more aspects that you need to take into account:

Aspect	Programming 👨‍💻	Software Engineering 🤝
Number of people	It’s individual	Team effort
Scale	The number of lines that one person is able to write	Maybe hundreds of lines written by different teammates everyday
Lifespan of a project	Maybe a couple months	Years, even decades
External dependencies	In that short lifespan is not critical to upgrade dependencies	With time is common to need to upgrade dependencies
Policies	A couple of established guidelines	A lot of rules to ensure quality code and maintainability
Modification	Low need for modification	High need for modification
Maintenance	Low need for maintenance	High need for maintenance

This table summarizes what it’s the difference between programming and software engineering, you need to think in higher lifespans, complex inter-dependencies that evolve over time and a greater scales of lines of code integrated over time. There is a quote that you need to keep in mind when talking about this:

Software Engineering is the set of policies, practices, and tools necessary to make that code useful for as long as it needs to be used and allowing collaboration across a team

Is a delicate balance that allow teams to keep alive projects in the long run.

Software engineering is programming integrated over time

When we are learning programming most of our projects only have a short lifespan, maybe two or four months, but in projects that will last for many years (even decades) you can’t think with the same mindset that you work when you developed these projects with shorter life.

If your project survives over time you come to realize some challenges that you didn’t imagine in the first place, with time every tiny decision has an impact on later modification and these little technical debts become a huge mortgage that you don’t know how to pay later. It is not an invitation to panic, it’s a recommendation to think about your code on a larger scale in every aspect: in time, in resource consumption or modification. Get your first guess and think of a 1.000x or 100.000x greater scale so you can see a glimpse of future problems. You don’t have to address them right away but definitely need to keep in mind to mitigate most important problems.

Maybe some examples clarify this topic:

You’re creating validations in your app, at some point you need to validate an email for creating a user, you thought “hmm? I just going to create a validation for this field in this section to validate this email” but then later on you need to create the feature of editing this email but at the moment there is another teammate working on that and he re-implements a function to validate email, at the end the feature it’s uploaded and everything seems fine. Weeks later it’s created a bug mentioning that the email: myorg@company.org works fine on the user creation but not for editing, so what’s happened here? Because there are two different implementations on email validations in one it works and in another doesn’t work resulting in duplicate logic and the risk of having incoherent behavior.
Another scenario, you imagine your application to work with a MySQL database but in some moment the people realized that there are use cases where PostgreSQL it’s better to develop new features that will be important in the future. So you now are migrating your data from MySQL to PostgreSQL but due to lack of good abstractions your code it’s tightly coupled to the original selected database so it’s going to cost more effort to be able to even start the migration process and ending writing the app from scratch.

Maybe you’re clever enough to imagine those scenarios but at some point all of us were so naive to even think that the database engine will never change.

Think in your code in terms of clean and maintainable and not in hacky or clever

When we are working on something difficult we are attracted to using some hacky thing that we found in StackOverflow and using in our code. But later on when something else needs to change in that file you don’t even remember what was the hack about because it’s written in an incomprehensible way that now looks like a hieroglyph or some dead language no longer used by humanity.

So in those cases when something difficult exists don’t write your code in terms of something that just works, prioritize something that indicates what are the steps performed and what is the meaning of every step clearly. Luckily nowadays there is no limitation on the length of the variables or functions to write our code so we can be as expressive as we want to.

For this example I was looking for old archive of previous programs to demonstrate this point:

# Code in Python
def main():
  N: int = eval(input())
  V = []

  for _ in range(N):
    C: int = eval(input())
    V.append(C)

  return V

if __name__ == "__main__":
  inputs = main()
  print(inputs)

Luckily this piece of code isn’t doing something so difficult but definitely doesn’t indicate too much about what it’s doing or the context of it. But with some rewriting reveals what was the original intention:

# Code in Python
def readScores():
  matches: int = eval(input())
  scores = []

  for _ in range(matches):
    scores.append(eval(input()))

  return scores

if __name__ == "__main__":
  scores = readScores()
  print(scores)

With this re-writing it’s more clear what we are doing: we are reading the scores of different matches of one user. The first section we were reading the user input to store a variable number of matches, then we read the scores and stored them in an array. The domain in which you are working it’s always useful to name things and you shouldn’t underestimate at the moment to write better code.

But is there a chance to improve even further? What if we need to read a different size of user scores repeatedly? Then maybe we can put this into a function that it’s able to read different sizes and also create a function to store the way to read user inputs:

# Code in Python
def readUserInput():
  return eval(input())

def readScores(matches: int):
  scores = []

  for _ in range(matches):
    scores.append(readUserInput())

  return scores

if __name__ == "__main__":
  matches: int = readUserInput()
  scores = readScores(matches)
  print(scores)

This scales even better! So you need not only to create correct code, you also need to create code that it’s understandable by others.

Code review it’s one of the more valuable things to guarantee clean and maintainable software

When you have another one that review your code you’re able to get an opinion that doesn’t share your same biases, so it’s valuable to have another point of view that helps you to ensure that other people are able to understand what you write in the first place (or at least is most probable that other people are able to.)

This is another big difference between programming and software engineering, as engineering is a team effort. You count on your teammates to help you with this kind of thing and reduce our personal biases in our code and be more consistent with the style of overall code.

When doing code review it’s helpful to have this things in mind:

Do it timely: when code review request is created try to do the review in the next 24 hours
Be polite and professional: don’t involve personal aspects in the code review, be assertive and point out the aspects of the code that doesn’t work
Submit small changes: in order to don’t overwhelm your reviewer do small changes (less than 200 lines of code) to the get an effective feedback
Write good change descriptions: in the first line describe the type of change you did (bug, feature, hot fix, etc.) and why you did it. When something is not approved, change the description if necessary.

Following these directives helps you to do great code review, giving feedback to other people it’s always difficult but it’s necessary for other people and ourselves to grow. The key to give great feedback is not to involve the being (like you’re disorganized, you're a bad communicator, etc.) it’s to talk about punctual actions (like in this section the variable names are ambiguous.) So we’re always talking about something near to reality and not from our personal biases.

Final Thoughts

The book Software Engineering at Google it’s a good recommendation to read if you want to grow far beyond just programming. The best thing about this book is that it’s free only to read right now, you can access it by following this link. At this moment I’m more excited to know about this because it is a problem that arises more frequently now that I’m more involved in larger codebases and I’m more confident writing code. If you want to improve in other aspects different from just writing a syntactically correct program this book is for you.