DEV Community: Felipe Bosi

Expanded literacy and the current state of software

Felipe Bosi — Tue, 14 Jan 2025 17:19:40 +0000

While reading Soon’s and Cox’s Aesthetic Programming book, I was faced with the “expanded literacy” concept that made me think on how different people see software.

Expanded literacy is the ability to write and read expanded with the ability to understand code. This extra literacy is linked to a better understanding of digital media and how our communication is being enhanced by new forms of writing languages. New languages that communicate both with programmers and that starts an action on a machine or online system.

Understanding how a computer and code works is one of the things that separates people that see software, AI, and similar things as a magical black box that can do anything that you want without any costs from the ones that understand the limits and costs of technology. Any software works on a set of commands that programmers give to a computer and the computer obeys them exactly as it is written. AI If you want to see this in a more visual and comical way, take a look at Josh Darnit’s video:

This is even true to Large Language Model and generative AI. For these cases, you can imagine that we have a program that generates a program/code based on the training data that it receives. This has a large cost on energy and manual work to tell the model what is correct and what is wrong, otherwise you'll end up telling your users that “Doctors recommend smoking 2-3 cigarettes per day during pregnancy.”.

Coming back to the expanded literacy idea, programmers know that a code written by a programmer, specially a senior one, has better performance and readability than a machine generated one. In non-coder terms, this means that a code written by someone costs less energy and we can understand better what it means and fix it, not only in terms of bugs that break the app, but also in terms of ethical consequences, like biased AI, people being able to use AI to teach them to build weapons or getting away with crimes ( For more read: "AI has a racism problem, but fixing it is complicated, say experts" and "Could a Chatbot Teach You How to Build a Dirty Bomb?"), or even hallucinations and strait up lies.

AI is a hot topic these days, but let’s focus on expanded literacy and differences between coders and non-coders that impacts everyone.

One thing that you'll see that is common among developers is that the “user doesn't care about the language that is used to build something” or “the best language is the one that pays my bills”, and I would say that both are correct. But that is only because the user doesn't have code literacy. However, the final user is directly impacted by the code, language and technology choices that we make. Even financially. The users start to feel that their computer or phone is “getting slower” and decide to buy a new one. Some of this can be credited to hardware getting older, but a lot more can be credited to these language, framework, paradigm and technology selection.

Although the user doesn't care about how we build the software that they use, this impacts how long a piece of hardware will survive, the amount of energy we use from their battery, and even the speed in which an action will take (for a detailed study, go to "Ranking programming languages by energy efficiency"). While users don't care about how software is made, most companies will try to cut corners and sell slow software as “blazing fast”. A term familiar to programmers, that in reality can mean anything from very slow to really fast, only the programmers that can check what is under the hood can tell which it is.

While users keep avoiding learning how computers and software works, companies will do their best to achieve a better revenue at the cost of the user's own money and our environment. Selling fake promises of a future where anything can be generated using natural language at low cost, while in reality we are forced to buy new computers and phones to keep up with trends we never asked for and that we don’t get any benefits from.

Visit my website

Naming conventions for React developers

Felipe Bosi — Wed, 16 Nov 2022 14:16:46 +0000

Naming conventions are something that helps to keep a codebase readable. On the frontend side, we use standard JavaScript conventions. Camel case for common variable names, pascal case for classes and components, and upper case for constant values. But this only covers the basics of naming conventions.

If we go to the React world, there are some other stable naming conventions; some come from when the primary way of creating React components was by using classes, and some are new, from React hooks.

One that comes from the old React, and is still used, is the prefix handle for functions that handles some component behavior, like handleSubmit or handleClose. Another common prefix from that era is the on__, which is used to declare that something happens on a specific event, like an onClick or onOpen. React class components also use two naming conventions that come from Object Oriented Programming, the use of setters and getters.

The major one from the hooks era is the useSomething. An eslint plugin even enforces this one. This is used both on the React default hooks and is forced to be used on any custom hook.

At last, one source of confusion reported by the team I work with is the name given to variables inside array iteration methods. Because of the similarity between singular and plural versions of entity names, a fast reading can make someone think that the plural version is singular and vice-versa. One way to solve that is to use generic names for the internal variable, like “item” or “element”. However, it’s up to the dev to do that or use the singular version of the entity since that proposition can change its value based on how long or complicated is the interation.

Two other classic naming conventions that can help anyone that wants to go further on this are https://www.oracle.com/java/technologies/javase/codeconventions-namingconventions.html and https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/general-naming-conventions.

This article was originally published on https://felipebosi.com/programming/naming-conventions/

The meaning of using tools to code

Felipe Bosi — Sun, 21 Feb 2021 17:49:14 +0000

You are on your computer writing code. You start a word and the autocomplete pops up. You press tab until you get the word you need. The autocomplete is reliable. It always appear when you start writing a command on the language that you use.

Now you are doing a test for a company. They insist that you use pen and paper. If you don't know it by memory, you don't really know it - they say. But is that really true?

Andy Clark and David Chalmers (https://icds.uoregon.edu/wp-content/uploads/2014/06/Clark-and-Chalmers-The-Extended-Mind.pdf) argues that this is false and I would argue that most programmers would agree with them. According to both, thinking and knowing isn't just a process that happens inside of a brain that is disconected of the rest of the world.

If you take a closer look of someone working, playing or thinking, the complete process always include going back and forth to the real world that is outside of our mind. Take the process of coding for example.

First we start by reading what we need to do and the code base we are working on. Then we start to code some simple lines and memorizing some informations. When this starts to get confusing or complicated, we externalize that information. We debug, use console.logs/prints to check information or even write some ideas on paper. We Google to check something that we "forgot" how to use and check for other pieces of code, on other repositories, that we wrote a while ago that we might be able to copy and paste. Finally, if everything went right, we push our code for review.

None of us would say that the guy that needed to use print statements and Google some informations doesn't know how his code work or that he doesn't know how to code. However, as we can see, not all of the information that he used is stored in his brain per say.

What the person on the example did was relaying on a tool to store that information for him. A tool that he knows it'll always be there for him to check and get that information at any moment in the same way we do with our memory.

He can trust Google to always have a possible solution. The console to log the data he asks for. The paper to store what he writes on it . And the piece of code that is already validated do work as it worked when he wrote it.

We are able to use tools to do a lot of diferent types of work. Thinking is just a diferent type of work. To nail something, a woodworker uses a hammer. People that works using propositional thinking uses text, search engines and other kinds of tools to be able to store/get every kind of information. That doesn't make anyone knows less or more. It's just a way to use the tools that are at you disponible.

The client doesn't care about how did you do something. No one asks if the Facebook or Google engineer used a seach tool to copy a piece of work. More important than knowing a lot of information by memory is to be able to get what you need to work fast, in a reliable way. To able to adapt to any problem, any new framework or language that you might need to learn.

Basic Java logical operators

Felipe Bosi — Thu, 22 Oct 2020 02:17:20 +0000

Coming from a philosophical background, one of the main parts of a language that I'm always curious is how they implement logical operators. Java doesn't do anything new on the logic field, but give us some powerful basic logic calculators.

The basic logical operators on Java are & (and), | (inclusive or), and ^ (exclusive or). The & operator does the classical test to see if both sides of the calculation are true, while the inclusive or (|) test if any of both sides are true, and the exclusive or (^) tests if only one side of the operation is true. The table bellow show the possible outputs for each different value:

However, there are some other calculators that enhances the power of the basic & and the |. If you add another of the same character to both operators, getting && and ||, the JVM will consider the full operation a conditional calculation, where it'll only calculate the second part of the operation if it can't assume the full boolean value using only the first part of the operation.

This type of operator can give you more control over calculations like: boolean y = (x >= 7) || (++x <= 9); where, if x is bigger or equal to 7, the second part of the operation isn't computed. However, if x isn't bigger or equal to 7, it'll get incremented, changing its value. With this, we can create complex logical structures.

On the example that I gave, a simple inclusive "or" gives a shape for an "if and only if structure" too. To fully understand it, we can't only read it as "x is bigger or equal to or x plus one is less than or equal to 9)" but also as "X will be incremented if and only if X isn't bigger or equal to 7". This can create a complex code that is difficult to read (as any Clean Code guide would say to you), but it also demonstrate how powerful a programming language like java can be and how it mimics the logical propositions.

5S and Code Quality

Felipe Bosi — Sun, 11 Oct 2020 21:16:12 +0000

5S is a well known quality system developed is Japan after the Second World War to guarantee that the company using it was delivering the best quality products the could, while creating a good work environment. One of the most famous company using it is Toyota. Its focus is on manufacture companies. However, this quality system also appear on code quality books, like the "Clean Code" and can help tech companies achieve a better code delivery by creating a work system around 5S' principles.

The 5 principles

1. Seiri or Sort

Seiri is sorting all items and removing anything unnecessary by tossing it away. The ideia is to create an environment where is easy to find anything needed, avoiding distraction by unused item and/or trash.

Based on this system, we should remove any unused code from our base. That mean, any code that is commented out (You ain't gonna need it), any comments that doesn't explain anything, and, of course, any code that doesn't do anything or that isn't even called on the rest of the base.

2. Seiton (Set in Order)

This principle aims to organise anything that was defined that is necessary but is out of place or is hard to understand its use. This creates a smoother work flow, where everyone knows what anything is based on a categorised system.

Thinking on a code environment, our folder system should use names that are easy to understand and every piece of code has to be on a folder that is related to the category that code should. That also means that we must avoid create folders that has lose meaning, like "utils" and "helpers", because putting code inside these types of folders is like putting it on a bland deposit, who knows what could be inside of it?

3. Seiso (Shine/Polish)

Seiso is cleaning and maintaining the workplace, equipments and machinery. This helps avoid accidents, by keeping everything is place and working as it should. Also, anyone that keeps cleaning their tools, are also more able to see when anything isn't working as it was supposed to be.

As we keep working, our code will get messier. We'll do some minor changes that shouldn't be made or make some poor choices to solve some bugs that we need to solve that exact moment. If we don't come back and clean all these problems, our code can get hard to read, or lose performance. The natural state of any code is to get "dirtier" as we keep working on it. So, the process of cleaning it is just a natural response that we need to do to keep it clean.

4. Seiketsu (Standardize)

Standardize any process, including the process to maintain the three principles above. On here we can also add standards for tests, for what programming paradigm your company will be using. Add/create any standard that can help programmers code faster and maintain the code base.

5. Shitsuke (Self-discipline/Sustain)

The last principle, but not less important, is related to self-discipline or to how can we sustain all the other 4 principles. Some people also translate this principle as "doing without being told".

The first part of it is having the discipline to maintain the other four principles. However, this principle also incorporate the study and training that is necessary to be able to always be better. Another important part of this is receive and giving feedback, specially from those that is on the frontline of the work, on our case, the developers and designers.

Tactics on how to review your own code

Felipe Bosi — Fri, 18 Sep 2020 02:29:07 +0000

Reviewing your own code can be a hard thing to do and no one writes perfect code every time on the first attempt. To avoid sending a PR with a code that isn't as good as I want it to be or that isn't according to my team's current practice, I'm developing some tactics to review my own code.

These tactics are still ideas in test and are a method that I'm developing thinking in my own qualities and problems. So, feel free to comment what other tactics you developed yourself to review your own code and ensure a better code quality.

1. Reproduce the problem / Test the design-prototype

The first thing that I do is to discover/reproduce the problem that I need to solve or to test the design/prototype for a feature, if you have one. With this first step you aim to know for sure what you're trying to solve or to implement.

During this step, you can also open a markdown or text file and write anything that you think you would need to know during the code process. On my case, I create a Vim function that calls a single work file where I write anything work related, but you can try to do something similar with any text editor.

2. Write the tests

Before you start to write the code, write any tests that you'll need to ensure that your code works. Even if you don't use a test suite or work on a TDD environment, you can write some series of steps to ensure that you code works and that it doesn't break any other feature.

On the company that I work right now, as a frontend developer, we don't have any tests. So, for this step, based on the data that I got from the first step, I write the steps to reproduce the error, adding some extra steps based on what I think could be impacted by the code that I'll need to write to solve the problem.

Even if you still don't know how to solve the problem and what it would impact, it's still important to write the tests before start coding, so you can have an idea on what you'll need to look for while coding. Also, you can come back and forth as you want to review the test that you wrote and ensure that they cover everything you are changing.

3. Solving the problem/ Implementing the feature

Write a code that solves the problem or implements the feature that you need to implement. Write it the way that you want to.

On this step you don't need to write the perfect code. You'll have time to review it later, make it better, to rewrite it on your companies' style or to use any library that you are forced to use by you companies' guide/colleagues (looking at you lodash).

4. Test the code

Test the code that you wrote using the test steps that you wrote and any test library/suite/framework that you use on your project.

5. Let the code rest a bit

With everything working, it is important to let the code rest a little.

On this step I try to stay away from code for at least 5 minutes, but not more than 15 minutes. I do this, because this isn't the only rest from code that I'll do during this self review steps. This is only a little rest to prepare for the next step.

6. Rewrite the code/solution

On this step you review the code that you wrote and rewrite it using the code style that you want or that you need to follow. You can also write any comments that you think the code need and any documentation that you need to write for you code.

7. Test you code again

After rewriting the code, you can test it again. But this time test every detail in every possible environment that you can think.

On the frontend side, I test my code on every possible browser and machine that we are supporting (we are dropping support for IE11 now, yeah!!!).

Try to test every edge case that you can imagine. Because the users will find that ones and some new more ways to create new bugs.

8. Commit your code, but don't create your PR yet

Commit you code and write a good commit message. I would advice to write not only the commit title, but a body too, explaining all your changes and how you tested it.

Commit messages are a live documentation that, if anything goes wrong, it can helps your team revert some bad code, understand what was happening on the code base on a specific time, and defends yourself if you need some backup when anything blows up on your companies' app(s). But don't create your PR yet, because this is the time for a longer rest.

9. Let the code rest for longer

This time you should let the code rest a while longer. You go tackle another ticket or do something else that takes more than one hour. The idea is that, when you return back to the original ticket, you had some more time to think about any edge cases that the test that you wrote before maybe doesn't cover, or any other style issue that you didn't remember on the first time you review you code.

10. Update your test and run everything again

At last, You can write any updates that you think the tests need and test everything again one extra time. If everything runs smoothly, the code is to ready be a PR and to be reviewed by the rest of the team.

Adding Storybook to a react project

Felipe Bosi — Wed, 26 Aug 2020 01:28:48 +0000

Storybook is an open source tool that helps developers to see, test and document components in isolation. It can be a very important tool for those who use the famous Atomic Design approach to componentization. And, as we'll see, it's a very easy tool to use and configure.

Here, we'll use it on a react project, put you can set it in any frontend project, independent of the framework that you are using.

Installing Storybook

The first step is to install the Storybook on any project that you like using npx:

npx sb init

This command will initialize the Storybook CLI that will into you code and install the best configuration and run npm run storybook to initialize the tool.

The React component

After the installation, it'll open the storybook app on http://localhost:6006. There you'll that the CLI already installed some examples. However, you can use any that you already have. On my case I used a component(written in TypeScript) that we extended from Material's-UI TextField:

import React from 'react';

import { createStyles, withStyles, WithStyles } from '@material-ui/core/styles';
import MuiTextField, { StandardTextFieldProps } from '@material-ui/core/TextField';
import classnames from 'classnames';

const styles = () =>
  createStyles({
    inputSmall: {
      height: '35px !important',
    },
  });

export interface TextFieldProps extends Omit<StandardTextFieldProps, 'classes'>, WithStyles<typeof styles> {
  size?: 'default' | 'small';
}

const TextField: React.FC<TextFieldProps> = ({ classes, size = 'default', InputProps, ...rest }) => (
  <MuiTextField
    InputProps={{
      classes: {
        input: classnames({
          [classes.inputSmall]: size === 'small',
        }),
      },
      ...InputProps,
    }}
    {...rest}
  />
);

export default withStyles(styles)(TextField);

What is important on this component is that it has a size props and that it exposes the Material-UI TextField props with the InputProps. This will allow us to create dynamic documentation and different stories on the Storybook.

Creating stories

A simple Storybook file start with the export of the metadata of the file that you are creating the story:

import React from 'react';

import { Story, Meta } from '@storybook/react/types-6-0';

import { TextField, TextFieldProps } from '../atoms';

export default {
  title: 'Atoms/Text Field',
  component: TextField,
  argTypes: {
    label: {
      name: 'Label',
      type: { name: 'string', required: false },
      defaultValue: 'Fake Label',
    },
    size: {
      name: 'Size',
      control: {
        type: 'select',
        options: ['default', 'small'],
      },
      defaultValue: 'default',
    },
  },
} as Meta;

As you can see, since we are using a React component, we start importing React. Then we import the storybook types and library, then the component and its type declaration.

The export default that comes bellow that is the component's metadata. On it, you can see the first field, title, where you can inform a folder structure and the component name. On my case, I'm putting the component inside the 'Atoms' folder as 'Text Field'. On the component field, you see the component declaration. Bellow it, you see and advanced Storybook configuration that let you declare some dynamic fields inside your documentation, as you can see in the image bellow:

Usually, Storybook will get these fields from your component without the need of you declaring them. However, in the case of this component, I had to declare them. Their declaration is simple. You create an argTypes property inside the metadata object, and inside of it, you declare the name of the props received by the component( in this case, label and size), give them the name you want to have on the Storybook documentation (like name: 'Name here'), a default value, and a type object, with the type of the field (like string, number or select), if the property is required and an array of options, if that makes sense for that field.

After the metadata, we can declare the template and the different stories that component can have:

const Template = (args) => <TextField {...args} />;

export const SizeDefault = Template.bind({});
SizeDefault.args = {
  size: 'default',
};

export const Small = Template.bind({});
Small.args = {
  size: 'small',
};

Here, on our case, the template is the TextField that receives and spread of the args object. For each different story we export it, binding it to the template and adding the different arguments. On our case, each story receives a label, with the value "Fake Label" that was declared as a default value on the argTypes, and the size that is declared on the templateName.args object.

On the image above you can see the different Text Field stories on the left side and the Default story on the center.

The Storybook library has a lot of important uses. With it we can create a documentation that uses the real code of a component, solving the problem of maintaining a documentation that gets old with any update on a project. However, right now, on our current application we are having issues with how to use Storybook on components that does GraphQL queries using Relay fragments.

If you liked the post, have any idea or any thoughts about Storybook, feel free to comment here or contact me.