Forem: Cristopher López Santana

Naming Matters: The Importance of Good Naming in Clean Code

Cristopher López Santana — Mon, 03 Apr 2023 06:51:36 +0000

The Importance of Good Naming in Clean Code

In software engineering, one of the most important aspects of writing clean code is good naming. Names matter because they help developers communicate their intent and reduce confusion, ultimately leading to better code quality and a more efficient development process.

The Impact of Bad Naming

Poor naming can create ambiguity and confusion, leading to wasted time and effort as developers struggle to understand what the code is doing. Just as in verbal communication, being clear and concise in code is essential to avoid misunderstandings and ensure that everyone is on the same page.

Basic Guidelines for Good Naming

To create meaningful and understandable names for your code, it's important to follow some basic guidelines based on the type of element you are naming:

Variables: Use nouns or short phrases with adjectives, such as userData or isValid.
Functions/Methods: Use verbs or short phrases with adjectives, such as sendData or inputIsValid.
Classes: Use nouns or short phrases with nouns, such as User or RequestBody.

Casing Conventions

Different programming languages and frameworks have different conventions for naming conventions, such as snake_case, camelCase, PascalCase, and Kebab-Case. It's important to choose a convention and stick to it for consistency across your codebase.

Naming Variables

When naming constants and properties, it's important to choose names that are descriptive and convey the type and purpose of the data being stored.

Ask yourself questions like "What type of data is storing?" and "What exactly is storing?" to find good names. For example, a constant representing a customer might be named customer, firstName, authenticatedUser, sqlDatabase.

Using short phrases with adjectives can help make the purpose of the boolean variable more evident. Examples of well-named boolean variables include isValid, didAuthenticate, and emailExists.

Naming Functions and Methods

A well-named function or method can convey its purpose and usage, making it easier for other developers to understand how to use it. Here are some tips for naming functions and methods in a clean and consistent manner:

Verb Usage: Functions and methods are typically named using verbs, as they describe actions. Choose a verb that accurately describes the function's purpose, such as "calculate", "generate", "validate", or "convert". Using a consistent verb tense throughout the codebase can also help maintain consistency and clarity.
Use Descriptive Names: A function or method name should be descriptive of its purpose, making it easy for other developers to understand what the function does. Avoid using generic names like "doSomething" or "processData" that do not convey specific meaning. Instead, use descriptive names like "calculateTotalPrice" or "validateEmailAddress".
Be Concise: While it's important to be descriptive, functions and methods should also be named in a concise manner. Avoid excessively long names or including unnecessary information. Use the shortest name possible that accurately conveys the function's purpose.

Naming Classes

To improve the readability and maintainability of code, it's important to use good naming conventions. This is especially important for classes, as they are the building blocks of an application. Good class names should be clear, concise, and reflect the responsibilities of the class.

The name of a class should be a noun or noun phrase that describes the abstraction that the class represents Avoid abbreviations, acronyms or obscure words, as this can make the code harder to read and understand.

The class should have a single responsibility and its name should accurately reflect that. Verbs should be avoided in class names, and there are different naming patterns that can be used, but consistency is key.

Simple Noun: This pattern uses a single noun to describe the class, for example, "Customer" or "Order".
Abstract Noun: This pattern uses an abstract noun to describe the class, for example, "Account" or "Transaction".
Adjective Noun: This pattern uses an adjective to describe the class, followed by a noun that describes the object or concept, for example, "ActiveUser" or "ExpiredLicense".
Compound Words: This pattern uses compound words to describe the class, for example, "SalesReport" or "UserSettings".

Common errors and pitfalls

Even when following the best practices of clean code, there are still common pitfalls and errors that can occur. Here are some of the most frequent ones:

Avoid being too specific or redundant with your naming. For example, using "userList" instead of "userMap" can lead to confusion and waste time for the team. Similarly, using "allUsers" when you only need a subset of users can also create confusion.
Use names that are distinct enough to avoid confusion. Avoid using names that are too similar, like "getDailyData" and "getDayData", as it can be hard to tell which method to use.
Be consistent with your naming conventions. Use the same terms across your classes to make it easier to read and maintain your code. For example, if you use "get"/"fetch"/"retrieve" in one class, use it consistently across all classes.

By following these guidelines, you can improve the readability, maintainability, and overall quality of your code, making it easier for you and your team to understand and work with.

Found a typo?

If you've found a typo, a sentence that could be improved or anything else that should be updated on this blog post, you can access it through a git repository and make a pull request. Instead of posting a comment, please go directly to my github repository and open a new pull request with your changes.

Starting with typescript

Cristopher López Santana — Tue, 08 Mar 2022 10:03:28 +0000

I am going share with you few things to try learn easy and fast how to use typescript in your projects. This is only an abstract about how to use typescript and basics things if you need more information about I recommend you to go to the official handbook. There you will find more and very good explain concepts and examples.

But lets start.

The primitives

So the primitives are the simplest units of data that Typescript give us to build the rest of our objects. Here the most used ones

boolean: it could contains True or False value.
number: Well not too much to explain about this, a number.
string: A concatenation of characters together, humans usually call it text.
Array: You could store multiple values of same type by order.
Enum: A friendly set of values.
Any: If you hate typescript and love JS you will love this type (bad pattern alert). This type could be any of the rest of types
Void: It means actually that, not really useful because only can store undefined and null. Used mostly as a return type on function that return nothing

here an example:

// Basic variable types
const isBoolean: boolean = true;
const numbers: number[] = [1, 2, 3, 4]; // This is how you declare an array of numbers

// Enums
enum GREETING {
  HELLO = 'Hello World',
  GOOD_MORNING = 'Good Morning World',
}

// Function and void type
function sayHi(): void {
  console.log(GREETING.HELLO);
}

Strange Types

If you just want to have a quick look to Typescript jump to next section.

"Do we really need those types?" That the question could come to your mind when you see next types for first time, but in some scenarios are needed. Probably you will not use this types but if you find yourself in any of this scenario you will know what to do.

Undefined and Null

It only can be their own value ( null or undefined ). It looks are not pretty useful by their own, like void, but if you want to use --strictNullChecks ( more info ) it would help you to specify when a variable or type could be undefined or null.

Unknown:

It exactly means that, a type that is unknown. When you receive a value from a function that you do not know what type is, we use the unknown type.

The main difference with any is that any let you use random attributes that the object could have. Using any property with unknown will throw a error.

if you want to know more about it here is a deeper explanation and distinction from the any type.

Never:

It is a type for something that never happen or should not exists. it is used in functions that returns exceptions or one that never returns like a infinity loop.

Here few examples:

function buildError(msg: string): never {
  throw new Error(msg);
}

function infiniteLoop(): never {
  while (true) {}
}

Difference between string/number/boolean/object and String/Number/Boolean/Object

If you are here just trying to learn and do not care much about what is what. As a rule of thumb you should try to avoid using uppercase ones.

If you are like me, you will probably want to know a bit more, so it is an easy explanation to have both ones. Typescript is a language that has been built over Javascript so it needs compatibility with types or objects that already exists.

You probably remember that we have things like this in Javascript:

var str = new String('My new string');
var nmbr = new Number(3);

So thats it is actually what represent that upper case types on Typescript. It is usually a bad pattern use them to create new types on Typescript. So you should avoid them as much as possible.

Go here if you want to know more about this.

Classes, interfaces, types

Classes: So classes are the same one that was introduced in javascript ES6. The good point of TS is that let you create your own types of objects. Here a basic example

class Dog {
  name: string;

  constructor(name: string) {
    this.name = name;
  }

  eat(): void {
    console.log('Glump');
  }
}

Interface is like the structure of a class, it do not implement how things work, only define the API that a objects or class are going to have. Here is an example:

interface Animal {
  name: string;
  eat(): void;
}

here an example of a class implementing the interface Animal and a function that returns that interface.

class Human implements Animal {
  name: string = 'John';

  eat(): void {
    console.log('gluh');
  }
}

class Bird implements Animal {
  name: string = 'Parrot';

  eat(): void {
    console.log('glip');
  }
}

function bornAnimal(type: string): Animal {
  if (type === 'BIRD') {
    return new Bird();
  }

  if (type === 'HUMAN') {
    return new Human();
  }
}

So Interfaces let us use objects without knowing exactly how it is implemented or his entire API, only understanding the part that is exposed by the interface.

Types: It is really similar to an interface, they are used to define the structure of an object but it has some difference, for now lets show how to use it

type Animal = {
  name: string;
  eat(): void;
};

if you want to know more about differences about interfaces and types here is a good post about it. To keep it simple lets say that its usually used to define literal object and for more compact definitions, for example to define states and props in React with Typescript.

Modifiers : private, public, protected

The modifiers define how a property of an object can be access. So lets show with examples an short explanations

public: It can be used by everyone, it is part of the public API of an object.
protected: Only classes that extend that object can use this property.
private: It is only usable inside the object, not accessible from outside of object not even from subclasses.

class AndroidPhone {
  public phoneNumber: number;
  public name: string;
  protected uiCustomization: string;
  private osCode: string = '<GreatAndroidFirmwareCode>';
}

class XiaomiPhone extends AndroidPhone {
  name = 'Mi A1';
  uiCustomization = 'MIUI (Name of system interface of Xiomi)';
  osCode = '<DoingGreatReWriteOfCode>'; // this is not allowed

  constructor(phoneNumber: number) {
    this.phoneNumber = phoneNumber;
  }
}

const johnPhone: AndroidPhone = new XiaomiPhone(3082);
console.log(johnPhone.phoneNumber);
console.log(johnPhone.uiCustomization); // this is not allowed

Found a typo?

React - JSX and Lifecycle

Cristopher López Santana — Sun, 19 Jul 2020 11:29:16 +0000

I would like to talk about typical things coming with ReactJS that you could miss when learning React. If you are in the process, this is going to help you to understand better JSX and Lifecycle. So let's start!

What is JSX?

JSX is the language that React offers to embed UI logic and render interfaces. JSX is really similar to HTML but is not the same. It runs inside of Javascript, for that reason I am going to give few tips to boost your knowledge about JSX and differentiate to html:

Properties and attributes names use camelCase instead of kebab-case found on HTML
- Example: tab-index => tabIndex
It Changes reserved words in js for a substitute
- Example: class => className
It always need a closed tag and it could be one line tag
- example: <input > => <input />
- example: <div> </div> => <div />
Style is a Javascript object:
- example: <div style:{ {backgroundColor: 'blue'} }></div>

Do not think that JSX is transformed to HTML directly, JSX is syntactic sugar for react element creation. This React Element is whose deal, following your instruction, to transform that into HTML. Here you will find more info about this topic in React official documentation.

Why should we use it?

There are a lot of reasons why you should use JSX, the first one and more important is because you are using React and you probably do not want to be creating elements like in the link from React documentation shown in the previous section.

But, if this is a point where you are thinking about using React or not let me try to convince you.

You will have more typo errors (helping you to find errors on UI)
It will give you the opportunity to create complex UI interfaces with a lot less code and less headaches
It is secure, JSX prevent injection attack because React DOM escapes any values embedded in JSX before rendering them.

When you are going to create an application/web page these points are really helpful. It reduces complexity and improves your productivity and the security of your project.

What is Lifecycle on React?

Lifecycles are the different stages that our component pass during his life in the DOM. The life of our component pass through three main phases:

Mounting
Updating
Unmounting

When our component is passing a specific phase it will call the correct function. In those functions, we could tell to the components to behave in a specific way (Download data, prepare the state, release resources...)

Cool, but what are those methods?

Ok, to keep it simple let me show you the more used methods

Building our component before showed in the application.
- constructor() Yep, famous constructor method, that method is to focus on state and properties set up. The reason behind this is that we want to show our component as soon as possible. Also, this is actually the only place where you are going to be able to assign this.state. Another thing to have in mind is that you must always call super() to send properties to React Component parent class.
Showing or render our component.
- render() here is where we are going to focus on tell to react how our component is going to looks like, for that purpose we use JSX.
Component is Mounted in the DOM.
- componentDidMount() This is a perfect method to execute code that require more processing (for example running requests) and it is going to be needed only at the beginning of the component lifecycle.
Component is Updated. It means that the state or props has changed.
- componentDidUpdate(previousProps, previousState) So this method is used when we are concern about how our component is evolving and we want to react differently depending of how our state or props are changing.
Unmounting our component. This happens when our component is removed from the DOM.
- componentWillUnmount(): this method is useful when we want to clear or free some resources.

Here is a graph to understand better the order and in which phase is every method:

Found a typo?

Learning about git!

Cristopher López Santana — Mon, 11 May 2020 21:19:54 +0000

In this post, I will try to give you some concepts to help you to start learning about git. Git is known by almost all programmers or even all of them. It manages all the changes made to your files and projects in an easy way.

I love to see git like a save state on a video game, if I fail in next boss I will restart from my previous state and I will give another try with a different strategy.

So let us begin!

What is git?

Git is a Version Control System. It means that git is going to help you to store and manage all the changes that you make to your file or project through the time. To do this, git works with repositories, and you have to commit those changes. Git runs on your local machine so you don’t need to have an internet connection.

How to start using git

First of all, you need to install Git on your local computer. You can download it from its website.
When you have already installed Git, you have to get into your Project folder

  cd projectFolder

or you can create an empty directory for your project using

  mkdir projectFolder

and then, run the command

  git init

This command will initialize a Git repository in this directory.

What is a repository?

A repository contains all the history of changes. It contains all the files managed by git. There are three principal local states related to files managed by git:

Working directory
Staging area
Git repository

Working directory is the directory in our computer which holds all our application files and folders.
Git repository contains all the changes that we save in git, that are finalized and uploaded by a commit.
The staging area is in between, is a holding area, a kind of queue when we are waiting for the changes for the next commit.

So, how can I add the changes that I’ve made to the staging area?

Simply, using the next command.

  git add myFile.txt

You can use this command followed by the name of the file that you want to add to this area or you can use a folder path that allows us to add all the files at the same time. This is

  git add .

We haven't committed our changes yet. In this area, you can move the files in and out without modify the git repository and review all the changes you have made before committing.

Committing changes

Once we have our files in the staging area we can save them in our git repo. We'll have to use another command:

  git commit -m "Commit message"

When we make a commit, we are going to save the changes in all files that were in the staging area.
Commit messages are messages that we add to our commits to describe which kind of changes you have done. These messages have to be simples.

How could I know the state of my repository?

Using the next command

  git status

Shows the status in both the working directory and staging area. It helps us to see in which state are the files you have modified so we can handle them.

Can I see all the commits I have made?

Yes! There is a command that outputs the history of changes. We have to use:

  git log

This returns to us very important information about our commit history, like the ID of the commits, the author, the date and where is the head.
It maybe looks a little confusing if you have multiples commits, but there are a few options that you can use to have a better vision of this log. My favorite one is:

  git log --all --decorate --oneline --graph

This one, in particular, draws a graphical representation in one line and it's very visual. Try it yourself!

Found a typo?

What is React and why is it useful?

Cristopher López Santana — Tue, 14 Apr 2020 14:23:46 +0000

Here we go again, what is react?

React is a powerful javascript library that helps us to create web applications. React focuses on how the appearance looks like and react to user interactions and creations of, what we call components.

The library was released on 2013 but it has been under development since 2011 by Jordan Walke a software engineer from Facebook.

What are components in React?

A Component is a concept that developers use to isolate a part of the UI and encapsulate similar features to make easy to reuse and maintain. Components must be independent of the rest of the application.

At the end, a component is a piece of HTML and JS code that show and interact with the user. So a button is a component but you can also have a component that is a compilation of components. You can have components inside other components also, creating them one by one and bounding them together.

So, for example, a button could be a component itself, but you can add this small component with a input and create a new component.

What is an application?

An application is a software that is created to final users. Yes, I know, it sounds ambiguous but it is what we have. So your android/iOS applications are that, applications, pieces of software made with a great UI/UX to everyone know how to use it (well... the good ones).

When we use React is to create Web Applications, applications are great because they run anywhere and it does not need to be store. Web applications have good points but also few bad ones. For example, they have reduced access to the operating system, performance issues, etc.

But good news, React have React Native, it reduces this kind of problems and lets us create great applications for mobiles using the same brilliant library.

State and Lifecycle? What they are?

State is a javascript object that contains the data relative to an object. We use them because we can update the state from a component to rerender it.

We update the state object using the setState() function. We have to initialize state when we create a component. React state is only valid in class based components.

Every React based component has what we call lifecycle methods. It is like a series of events (or functions) that are going to be called automatically by React at certain points during this lifecycle.

It has three phases:

Mounting: Puts elements into the DOM.
- constructor(). This methods is called before anything else.
- render() method it’s always required. Makes the content visible on the screen.
- componentDidMount(). It’s called after the components will shows up. Good place to do data loading.
Updating: A component is updated when the state or props is changed.
- componentDidUpdate(): Even if you are on the updating phase, render will be call to show the content on screen when change is produced.
Unmounting: Stop showing components on screen.

componentWillUnmount():

You always complicate things a lot, why I need it?

By using React, we can create Web applications with reusable components, and change data without reloading the page. So we can create large web applications easily.

Found a typo?

Understanding Redux

Cristopher López Santana — Wed, 12 Feb 2020 17:55:43 +0000

First, this post is not to learn redux, it is to clarify few key concepts. So its about resolving doubts more than trying to explain Redux. I would recommend Redux documentation if you are trying to find a resource to start learning redux.

What is redux?

I will try to keep simple. Redux is a small library to store the central state and make it predictable. For that purpose it use functional programming paradigm concepts.

It keeps control of how you manipulate the state giving you three basics concepts for it, Actions, Reducers and Store.

Redux just let you follow a unidirectional data flow state modifications, and it starts by Actions. Actions send the data to the correct Reducer and Reducers modify the state.

Wait wait... actions? reducers? state?

Ok, I will try to give you few keys to understand this concepts:

Actions are basically the definition of the change that you are going to make in the state. They are the responsible to take and pass the information to the proper reducer. For that actions, return a plain javascript object. The only value needed by redux is Type, the rest of them are up to you. Type is used by Redux to identify the correct reducer.

// Example of a plain object returned by an Action
const SET_USER = 'SET_USER'

...

{
  type: SET_USER,
  payload: {id:2, username: 'John'}
}

BONUS

It is a good practice define our action types because they are going to be used around our application.

Reducers, here is where we said to redux how the state is going to be changed. Reducers receive the information obtained by actions and return the new state. Redux give us one restriction here and it is that Reducers have to be Pure Functions.

function setUser(state, action) {
  return Object.assign({}, state, {
    user: {
      username: action.payload.username,
      id: action.payload.id,
    },
  });
}

Store is the object that keep control over the state. So if you need, update the sate, listen changes, etc. the state is your guy. It is a singleton, that means that we only have one in our application.

Pu... Pure Functions?

Pure functions is a term that comes from functional programming. This term means that a function should do not produce any external side effect (Change or read global values, make API calls, write or read files, etc).

That means that pure functions are deterministic. In other words, you can know the output from specific inputs. This is key when you want to keep something like your application state under control.

Ehm, What is functional programming?

This may take more time to explain it, but I will give you few things to understand a bit what we are talking about.

Functional programming is a paradigm that avoid changing state and mutable data. It create solutions treating the software as compound of mathematical functions (or pure functions).

So if you compare with Object Oriented is probably really different. If you would like to know more about Functional Programming here is a place to start.

I feel its too much, Do we really need it?

It depends...

If you are creating a really small app the answer is no, but if you are creating a big application and you have a central changeable state this is probably the solution to your problems.

Another thumb rule is giving by Dan Abramov:

I would like to amend this: don't use Redux until you have problems with vanilla React.

So, basically, if you are reading about redux and it does not help with your headaches, it is probably because it is not the answer.

I do not like it, Do you have something better?

I do not know if they are better, but I have few options that you could check. Probably depending of your needs you will find them more helpful in your situation.

Found a typo?

Middleware on redux

Cristopher López Santana — Sun, 09 Feb 2020 19:22:46 +0000

If you are starting to learn Redux, middlewares could be a pain know what it is and why we need them... So I am going to try to give you few keys (and links) to help you in your learning process.

What is a middleware?

A middleware is usually called "Software glue". It is usually a piece of software that it is in the middle of two softwares, and it makes easy the communication between them.

A middleware become popular with the beginning of Operating systems architecture. It made easy the way that engineers get/set data to operating system.

In redux documentation says:

Provides a third-party extension point between dispatching an action, and the moment it reaches the reducer.

So it is basically a piece of code between actions and reducers.

Why we need them?

Yes, I was thinking the same, why we have to complicate things that much? But hold on, it have good a reasons.

Actually, It is technically possible do it without middlewares. But, as a rule of thumb is a bad idea and you could mess things.

Redux try control access to state and reduce any problems. For that purpose they try to give you few guidelines. They usually are aimed to reduce complexity and organize everything by single responsibility. The things that clarify me this were:

It made easy the process to create new kind of actions. The big thing here is we are going to probably send the dispatch to our new action. That have two disadvantages:
1. Made the method signature complex and a bit difficult to read.
2. Now we have two different ways to call actions.
We encapsulate this complexity from our UI Components. In that way every action is executed in the same way. If we change that actions in the future, and it does not need any middleware, Components does not need any change.
Middleware are composable in a chain.

Basically, This is a SOLID solution.

If you want to know more, Stackoverflow has a great thread talking about this doubts:

Cool but, Where is this exactly in Redux?

The architecture inside redux looks like this:

Ehm but, How it works?

So easy, thinking on Thunk Redux, when you dispatch one of yours new ThunkActions, is going through redux environment, but not directly to reducers. It first pass through middlewares and there, Thunk detect this action as a ThunkAction because it takes only one argument, a Redux store.

After that, it will execute your "normal" actions in the order that they have been resolved. But this action will go finally to our reducers (But they could also pass through any other middleware)

I think this post explain better.

How I create my own middleware?

As we saw on what its a middleware and where it is, it is a piece of code between actions and reducers.

Here a small example:

const awesomeMiddleware = store => next => action => {
  if (action.type === 'MY_ACTION') {
    console.log(`My awesome middleware is working!`);
    store.dispatch(action.payload.otherAction);
  }
  next(action);
};

const store = createStore(counter, applyMiddleware(awesomeMiddleware));

The code is not really good, but it works for what we are trying to show. The power of middlewares. Probably the only thing for what you need a little more explanation is about Next (If you need more) . Next is a function that the middleware call when it finish with the assigned task. This sends the action to our reducer or another middleware.