What makes a function easy to understand? How can we write functions in a way that communicates its intent well? How can we translate the function's general idea to a casual reader? Each section of this chapter provides an idea.

## Small!

Your functions should really only be a few lines long. The way to achieve this is to do as much method extraction as possible. Bob provides an example of a 64 line function, which he shortens to this:

```java
 public static String renderPageWithSetupsAndTeardowns(
   PageData pageData, boolean isSuite
 ) throws Exception {
   boolean isTestPage = pageData.hasAttribute("Test");
   if (isTestPage) {
     WikiPage testPage = pageData.getWikiPage();
     StringBuffer newPageContent = new StringBuffer();
     includeSetupPages(testPage, newPageContent, isSuite);
     newPageContent.append(pageData.getContent());
     includeTeardownPages(testPage, newPageContent, isSuite);
     pageData.setContent(newPageContent.toString());
   }

   return pageData.getHtml();
 }
```

And then this:

```java
public static String renderPageWithSetupsAndTeardowns(
   PageData pageData, boolean isSuite) throws Exception {
   if (isTestPage(pageData))
     includeSetupAndTeardownPages(pageData, isSuite);

   return pageData.getHtml();
 }
```

Note that he reduced many of the 64 lines into functions. Then, he reduced the block inside the `if` statement into a single function. Ideally, everything inside `if` statements, `else` statements, `while` statements, and so on should be a single function call.

## Do one thing

Functions should do one thing. They should do it well. They should do it only.

The famous single-responsibility principle, the “S” in SOLID, applies to functions as well.

## One level of abstraction per function

In order to make sure our functions are doing one thing, we need to make sure that the statements within our function are all at the same level of abstraction. You shouldn't be mixing high-level things such as `getHtml()` with low-level things such as string manipulation.

### Reading code from top to bottom: *the stepdown rule*

Every function should be followed by those at the next level of abstraction so that we can read the program, descending one level of abstraction at a time as we read down the list of functions.

Bob says that writing a function with just one level of abstraction is very difficult to do consistently. But learning how to do it is important. It is the key to keeping functions short and making sure they do one thing.

## Switch statements

What about `switch` statements? How do we make them do one thing when they're designed to do multiple things?

Consider the function:

```java
public Money calculatePay(Employee e)
throws InvalidEmployeeType {
  switch (e.type) {
    case COMMISSIONED:
      return calculateCommissionedPay(e);
    case HOURLY:
      return calculateHourlyPay(e);
    case SALARIED:
      return calculateSalariedPay(e);
    default:
      throw new InvalidEmployeeType(e.type);
  }
}
```

This function has several problems. It's big and it will grow. But the biggest problem is that there is an unlimited number of functions that will have the same structure, such as `isPayday`.

The solution is to bury the `switch` statement in the basement of an abstract factory and never let anyone see it. The factory will use the switch statement to create appropriate instances of the derivatives of `Employee` and the various functions will be dispatched polymorphically through the Employee interface.

```java
public abstract class Employee {
  public abstract boolean isPayday();
  public abstract Money calculatePay();
  public abstract void deliverPay(Money pay);
}
-----------------
public interface EmployeeFactory {
  public Employee makeEmployee(EmployeeRecord r) throws InvalidEmployeeType;
}
-----------------
public class EmployeeFactoryImpl implements EmployeeFactory {
  public Employee makeEmployee(EmployeeRecord r) throws InvalidEmployeeType {
    switch (r.type) {
      case COMMISSIONED:
        return new CommissionedEmployee(r) ;
      case HOURLY:
        return new HourlyEmployee(r);
      case SALARIED:
        return new SalariedEmploye(r);
      default:
        throw new InvalidEmployeeType(r.type);
    }
  }
}
```

## Use descriptive names

This is the same idea described in chapter 2. The smaller a function is, the easier it is to give it a descriptive name.

We shouldn't be afraid of long names. A long descriptive name is better than a short enigmatic name. A long descriptive name is better than a long descriptive comment.

## Function arguments

The ideal number of arguments to a function is 0, followed by 1 and 2. 3 or more arguments should be avoided.

Arguments make the code less readable. Arguments make the code harder to test, as you have to test every combination of arguments.

### Common monadic forms

Monadic functions are fairly common and are usually done right. You may be asking a question about a value, such as `boolean fileExists("myFile")`. Or you may be transforming an argument into something else and returning the transformed value.

### Flag arguments

Never do flag arguments. Passing a boolean into a function is a terrible practice. If there are two cases, create two functions.

### Dyadic functions

There are times when dyadic functions are necessary and natural, such as `point P = new Point(0, 0)`.

We will have to write dyadic functions eventually. However, they should be avoided and converted to monads, when possible. They are not readable and you may get the order of the arguments wrong.

### Triads

Think very carefully before creating a triad. They have the same problems as the dyads but doubled.

### Argument objects

A way of reducing arguments is passing objects. Consider the difference between the following declarations:

`Circle makeCircle(double x, double y, double radius);`

`Circle makeCircle(Point center, double radius);`

### Argument lists

We may want to pass a variable number of arguments into a function.

String.format("%s worked %.2f hours.", name, hours);

If the variable arguments are all treated identically, as they are in the example above, then they are equivalent to a single argument of type `List`. By that reasoning, `String.format` is actually dyadic. Indeed, the declaration of `String.format` as shown below is clearly dyadic:

`public String format(String format, Object... args)`

### Verbs and keywords

In the case of a monad, the function and argument should form a very nice verb/noun pair, such as `write(name)`.

In the case of a dyad, we can encode the names of the arguments into the function name. The function `assertEquals` might be better written as `assertExpectedEqualsActual(expected, actual)`. This getting the arguments order wrong.

## Have no side effects

Side effects are things your function does which are not defined in its name. Try to find the side effect in the following function `checkPassword`:

```java
public boolean checkPassword(String userName, String password) {
  User user = UserGateway.findByName(userName);
  if (user != User.NULL) {
    String codedPhrase = user.getPhraseEncodedByPassword();
    String phrase = cryptographer.decrypt(codedPhrase, password);
    if ("Valid Password".equals(phrase)) {
      Session.initialize();
      return true;
    }
  }
  return false;
}
```

The side effect is `Session.initialize();`. The name of the function is misleading, as it does not match exactly what the function does. Thus, a password check can only be made when it is safe to initialize the session.

## Command query separation

Functions should either do something or answer something, but not both. Consider the example:

`public boolean set(String attribute, String value);`

This function sets the value of an attribute and returns whether or not the operation was successful. The problem with this function is it creates statements like:

`if (set("username", "unclebob"))...`

This is confusing when you read it for the first time. The solution is to split the queries into different functions.

## Prefer exceptions to returning error codes

Error codes create deeply nested structures, as you have to deal with the error code immediately. Instead, use exceptions:

```java
try {
  deletePage(page);
  registry.deleteReference(page.name);
  configKeys.deleteKey(page.name.makeKey());
}
catch (Exception e) {
  logger.log(e.getMessage());
}
```

### Extract try-catch blocks

Try-catch blocks are already ugly. So try to make them more readable by extracting their blocks:

```java
public void delete(Page page) {
  try {
    deletePageAndAllReferences(page);
  }
  catch (Exception e) {
    logError(e);
  }
}
```

## Don't repeat yourself

Bob says that duplication may be the root of all evil in software. Many principles and practices have been created for the purpose of eliminating it. Consider how object-oriented programming serves to concentrate code into base classes that would otherwise be redundant. Structured programming, Aspect Oriented Programming, Component Oriented Programming, are all, in part, strategies for eliminating duplication.

## How do you write functions like this?

Writing software is like any other kind of writing. When you write a paper or an article, you get your thoughts down first, then you massage it until it reads well. The first draft might be clumsy and disorganized, so you wordsmith it and restructure it and refine it until it reads the way you want it to read.

When we write functions, it is normal for them to come out long and complicated. They have lots of indenting and nested loops. They have long argument lists. The names are arbitrary, and there is duplicated code.

It is our job to massage and refine that code, splitting out functions, changing names, eliminating duplication. Shrink the methods and reorder them.

In the end, we wind up with functions that follow the rules Bob has laid down in this chapter.

No one could write them that way to start.

## Conclusion

Wow, that was a long chapter! But a lot of good insights came from it.

Every system is built from a domain-specific language designed by the programmers to describe that system. Functions are the verbs of that language, and classes are the nouns. The art of programming is, and has always been, the art of language design.

This chapter has been about the mechanics of writing functions well. If you follow
the rules herein, your functions will be short, well named, and nicely organized. But never forget that your real goal is to tell the story of the system, and that the functions you write need to fit cleanly together into a clear and precise language to help you with that telling.


Functions are the first line of organization in any program. This chapter focuses on how to write them well.

Functions - Clean Code, Chapter 3

Since a large chunk of what we do in software development is naming things, Bob has dedicated an entire chapter to it.

## Intention-Revealing Names

Bob introduces this chapter by showing a bad way to name variables: explaining it through a comment.

```java
int d; // elapsed time in days
```

Why not just name it `elapsedTimeInDays`?

The problem with explaining it through a comment is that it is insufficient. The code that uses a variable called `d` will not be as readable as the code that uses `elapsedTimeInDays`. It will be hard to tell what the code does.

Bob also gave this example:

```java
 public List<int[]> getThem() {
   List<int[]> list1 = new ArrayList<int[]>();
   for (int[] x : theList)
     if (x[0] == 4)
       list1.add(x);
   return list1;
 }
```

Since the names `List, getThem, list1, x` are not revealing their intentions, it's impossible to know what this code does. So always use names that explain what your code does.

## Avoid disinformation

This chapter lists a few things to prevent your names from sending other developers in the wrong direction:

* Don't use names that mean something to developers if they don't actually mean it. For example, don't use List if it is just an array and not the actual list from Data Structures.
* Don't use names that are hard to differentiate from one another on a quick read.
* Don't do things such as using l and O as variable names, because they're very similar to 1 and 0.

## Distinguish stuff from one another

Sometimes we write code to satisfy the compiler. We add a number to a variable so that it is different from another variable, we misspell it, among other things.

Imagine finding two variables named `payment` and `paymentObject`. Imagine finding a function named `removeFromCart()`, but then afterwards finding a function named `removeOneFromCart()`. How would you know that `removeFromCart()` doesn't remove just one item from the cart?

## Use pronounceable names

If a name is unpronounceable, it probably needs to be explained to new developers.

Also, Bob says, it is a little bit difficult to discuss it in meetings without sounding like an idiot.

## Use searchable names

Code editors nowadays have a lot of useful tools to search pieces of code. However, in a large codebase it is very difficult to find what you look for without getting a lot of other results.

Generic variable names can yield hundreds of results when searching for them. So we have to name them in a way that makes them easy to be found.

## Name functions with verbs

Functions and methods should usually have a verb in their name because they do something (obviously!).

If it returns a boolean, name it with `is`. If it is an accessor/mutator, name it with `get`/`set`. Otherwise, use an appropriate verb for what it does.

## Use the same name for the same stuff

Pick one word for one abstract concept and stick with it. If there already is a lot of functions with the verb `fetch`, do not use `get` or `retrieve` for new functions. Stick with the existing patterns.

However, some verbs are ambiguous. You might use `add` for a function which performs a mathematical operation and for a function which inserts a value into an array. In this case, it is better to use different verbs, since they perform different tasks.

## Use solution domain names before problem domain names

Remember that people who read your code are programmers. They might not be fully aware of every aspect of the project's business rules. They will always know what a `AccountController` is, though.

When there is no space for solution domain names, use problem domain names. At least the programmer can ask an expert if they're unsure what it means.

## Add meaningful context

Some names are meaningful in and of themselves. If a name isn't, it is our job to provide the necessary context so that our code is readable.

Variables named `street`, `city`, `state` are obviously referring to an address. But what if you see the variable `state` out of context? How would you know it is the state of an address? The best solution here would be to create a class called `Address`.

## Don't add gratuitous context

Do not add context that makes it harder to code. If you have an application called Gas Station Deluxe, don't add a `GSD` prefix to every class. You will type in `G` and your IDE's autocompletion list will be very long.

## Conclusion

This chapter is very related to human social skills more than anything else. This is because the problem of naming things is a cultural one. It relates to our ability of communicating with our team, something that seems to be lacking with developers when compared to other professions. Chapter 2 is here to change that.

This chapter contains ideas on how to communicate your code's intentions through names

How to name variables, functions, etc - Clean Code, Chapter 2

First, a brief introduction. This will be a series of articles dedicated to the book Clean Code written by Robert C. Martin. The main reason for this is for studying purposes. I also think that the concepts taught in this book are some of the most important things you can learn as a programmer. As the book says, entire projects can be ruined by bad code and a fortune is spent trying to fix it.

## Code will never be gone

Robert C. Martin (or uncle Bob) argues that there will always be code, because there will always be the language in which we express the requirements to a machine. This language might get closer to the actual requirements, but it will always be a language, and therefore code. I agree with that. The human mind and a machine's "mind" are fundamentally different. They will always require translation between each other.

## Bad code and it's consequences

Bad code is something that even beginners know how to recognize. They might find it hard to read or get tired of all the repetitions. Bad code makes us feel like something isn't right while working.

If only that was the end of it. The reality is that it causes a lot of difficulty maintaining large projects. This can be very costly to companies, as management finds out that programmers will have to stop what they're doing and figure out this mess. Management might try to fix it by hiring more programmers, but this will only make things less efficient. They are new to the codebase and it will take time before they can untangle the messy code and be a little productive.

Eventually, the solution is a miraculous redesign that will fix all problems. However, the new project will be in a race to catch up with the old one as the old one is also getting new features (a company can't just stop everything and wait for a redesign). This race can take several years. When it ends, the "new" codebase might be just as messy as the old one.

## Let's face it: if we write bad code, it is our fault

I think we all have been tempted to blame something else for bad code. Tight deadlines, clueless managers, changes in requirements, etc. I have felt the pressure of delivering something quickly and thinking: "This is pretty bad code, but I don't have time to think about this right now".

The thing is, looking back, I did have the time. That piece of bad code cost me a bunch of time later on in the project.

How do we deal with the unrealistic expectations of managers, deadlines, marketing, etc? We have to comunicate with them, something that programmers usually don't do enough of. Often times these people have absolutely no idea what we do and they look to us for information. As Bob says, it's their job to defend the schedule and it's *our* job to defend the code.

We have to accept it: bad code means **going slow**.

## Clean Code, according to experienced programmers

Bob asked for aspects that define Clean Code. These were the responses:

### Bjarne Stroustrup, inventor of C++ and author of The C++ Programming Language

* Is *elegant* and *efficient*
* Makes it hard for bugs to hide
* Has minimal dependencies, to ease maintenance
* Has complete error handling
* Has performance close to optimal, with no *unprincipled* optimizations
* Does *one* thing well

### Grady Booch, author of Object Oriented Analysis and Design with Applications

* Is *simple* and *direct*
* Reads like a well written prose
* Never obscures the designer's intent
* Is full of *crisp* abstractions and *straightforward* lines of control

### “Big” Dave Thomas, founder of OTI, godfather of the Eclipse strategy

* Can be read and enhanced by *other* developers
* Has unit and acceptance *tests*
* Provides *one* way of doing *one* thing
* Has minimal dependencies
* Provides a clear and minimal API
* Should be *literate* (readable by humans)

### Michael Feathers, author of Working Effectively with Legacy Code

* Looks like it was written by someone who *cares*
* If you try to improve it, you're led back to where you are

### Ron Jeffries, author of Extreme Programming Installed and Extreme Programming Adventures in C#

* Runs all the tests
* Contains *no duplication*
* Expresses all the design ideas that are in the system
* Minimizes the number of entities such as classes, methods, functions, and the like

### Ward Cunningham, inventor of Wiki, inventor of Fit, coinventor of eXtreme Programming, motive force behind Design Patterns, Smalltalk and OO thought leader

* When you read it, it is pretty much what you *expected*
* Makes it look like the language was written for the problem

## Conclusion

### Authors are read

Authors spend very little time writing, compared to the time spent by the reading. This is the same in programming. We spend a lot of time reading code in order to write our own. For this reason, code should be easier to read even if it is harder to write.

### The boy scout rule

"Leave the campground cleaner than you found it."

Leave your codebase cleaner than you found it.

This chapter creates the concept of Clean Code and defines the reasons for it's existence

What is Clean Code and why use it? - Clean Code, Chapter 1

When developing a React project, we constantly have to create new components. This is good practice, as it follows the principles of Atomic Design where you develop a component for every "atom" of your project's Design System.

However, there are some things that have to be done every time we do this. They are usually done by copying and pasting another component, renaming it, renaming constant/variable names inside the files and erasing the rest of the code.

We want to automate this because:

1. It saves time
2. It keeps the boilerplate code consistent across your app

In this article, I will show you how to generate a new component with a simple command.

## Installing Plop.js

Add `plop` to your project with:

```bash
$ npm install --save-dev plop
```

or, if you're using yarn:

```bash
$ yarn add -D plop
```

## Creating template files for your component

Create a folder called `generators` at the root of your project. Inside, create another folder called `templates`.

### Index file

Now, create your index React component template file. In my case, every component has an `index.tsx` file so I will create a template file called `index.tsx.hbs`:

```jsx
import * as S from './styles'

const {{pascalCase name}} = () => (
  <S.Wrapper>
    <h1>{{pascalCase name}}</h1>
  </S.Wrapper>
)

export default {{pascalCase name}}
```

What does this do?

When I tell it to generate a component called Button, for example, it will generate an `index.tsx` file like so:

```jsx
import * as S from './styles'

const Button = () => (
  <S.Wrapper>
    <h1>Button</h1>
  </S.Wrapper>
)

export default Button
```

### Styles file

I'm using styled-components so I will also need a `styled.ts.hbs` file:

```js
import styled from 'styled-components'

export const Wrapper = styled.div``
```

This is what we have so far:

![generators](/img/2022-01-29_19-32.png)

## Making it work

Inside the `generators` folder, create a file called `plopfile.js` and paste this code:

```js
module.exports = function (plop) {
  plop.setGenerator('component', {
    description: 'application component logic',

    // inquirer prompts
    prompts: [
      {
        type: 'input',
        name: 'name',
        message: 'component name?'
      }
    ],

    // actions to perform
    actions: [
      {
        type: 'add',
        path: '../src/components/{{name}}/index.tsx',
        templateFile: 'templates/index.tsx.hbs'
      },
      {
        type: 'add',
        path: '../src/components/{{name}}/styles.ts',
        templateFile: 'templates/styles.ts.hbs'
      }
    ]
  })
}
```

This will create a folder inside your components folder with the files. You can erase or add actions depending on how many files you have for each component.

Finally, we'll create the script that will do all this work for us. In your `package.json` file, inside `"scripts"`, add the following line:

```js
"generate": "yarn plop --plopfile ./generators/plopfile.js"
```

## No more copying and pasting!

Now, all you have to do to create a new component, for example a `Button`, is go to your terminal run the command:

```bash
$ npm run generate Button

or

$ yarn generate Button
```

That's it! It will generate the `Button` folder inside `components` which will have the `index.tsx` and `styles.ts` files. If your components have more files (tests, for example) you can easily create the template file and add it to your `plopfile.js` actions.


Generate new components without having to import basic libraries and write boilerplate code

Functions - Clean Code, Chapter 3

Functions are the first line of organization in any program. This chapter focuses on how to write them well.

How to automate component creation in React

Generate new components without having to import basic libraries and write boilerplate code

How to name variables, functions, etc - Clean Code, Chapter 2

This chapter contains ideas on how to communicate your code's intentions through names

What is Clean Code and why use it? - Clean Code, Chapter 1

This chapter creates the concept of Clean Code and defines the reasons for it's existence