DEV Community: Rachel Curioso :D

Refactoring - What problem on your code do you want to fix?

Rachel Curioso :D — Sat, 09 Nov 2019 15:42:35 +0000

When we start to study refactor techniques, we came across several (anti)patterns that we can find in our code. Many of these patterns have names that aren't very clear and, at first sight, is hard to understand what they are.

Having this difficulty, I decided to create a guide to identify which patterns are according to the pain that we feel when we are viewing the code.

1. Code that has grown way more than they should (Bloater)

The same group of data is repeated in several different places = Data Clump
There are too many primitives, a lot of constants or primitives that should be an object = Primitive Obsessions
Methods that are too long = Long Method
Classes that are too large = Large class
We have way too many parameters = Long parameter list

2. Problems arising for misuse of object-orientation (Object-Orientation Abusers)

A lot of ifs/switch case = Switch Statement
Temp Variable = Temporary Field
Two classes with the same function but different names = Alternative Classes with Different Interfaces
My child class uses very little of the father class = Refused Bequest

3. Problems that make any code change way too hard, because we have to modify several different places to change something(Change Preventers)

To make a simple change, I need to go through several different methods in a class = Divergent Change
In order to change something, I need to go through several different places in different classes = Shotgun Surgery
If I need to create a child class for class X, I also need to create a child class for class Y = Parallel Inheritance Hierarchies

4. There is a lot of useless stuff in there. Their presence only difficult the code understanding (Dispensable)

Duplicate code = Duplicate code (duh)
There is a class that doesn't do anything = Lazy Class
The piece of code was created thinking about the future (that probably never came) = Speculative Generality
I have a class that is a bunch of getters and setters, and it exists only to be manipulated. Probably it serves only to be a database interface = Data Class
Comments = Comments (duh2)

5. The classes are too close. They are dependent on each other, and there is a lot of coupling (Coupling)

Methods that access a lot of gets of another object = Feature Envy
Object that calls another object that calls another object that calls anot... = Message Chains
A class acts only as an intermediary for another = Middle man
A class use methods and fields of another class = Inappropriate Intimacy
I Installed a lib that doesn't do everything that I need = Incomplete Library Class

These patterns only identify what to look when we want to refactor. For every pattern there is a recipe to fix that. You can find all in this website

If you want to/can invest a little more, I advise you to buy the "refactoring" book, because they have (waaaaay) more examples than the website mentioned above, and is a good source for consultation.

imagem do post de Alex Andrews

Identifying the dirt in our code - third party, tests and classes

Rachel Curioso :D — Tue, 15 Oct 2019 00:44:53 +0000

When I started with the clean code series, the intention was not only to fix my knowledge about the subject but to pass on the knowledge that I acquired.

This series also serves as a quick guide to the book. When I need to remember some topics, I can find faster what I'm looking for.

On the first post, I talked about names, functions, and comments.

On the second post I talked about formatting, object and data structure, and how to handle errors.

In this last post, I talk about how to handle third-party code, how to organize your tests and your classes.

In addition to these 9 topics, the clean code book talks about dealing with systems, some more topics about Java, and it also covers how to identify some code smells.

I decided not to cover these topics because I would like to make the series more generic and friendly to all languages. Also because I don't have so much practical knowledge about building systems from scratch, and I also believe that an exclusive series on refactoring could better address code smells since in the clean code book the theme is a bit superficial.

That said, we can start with the topics of today's posts:

Handle with third-party code

We hardly make a code 100% alone. We usually use some lib to help us, and most of the times, some colleagues contribute to the code

It's important to learn how to handle the code boundaries, identifying where our code ends and the other's code begins so we can maintain the system working more easily.

One of the problems with using third-party code is that they usually have more features than we need and this can make our code behave strangely.

Encapsulate your library!

The best way to solve this problem is to encapsulate the library we will use in a class, and pull only the methods that we will need.

Another advantage of encapsulating a third-party library into its own class is by doing so, we can make it easier to change the lib versions or even swap the library itself.

Let's suppose we have a library in our code that connects to a payment service. When we want to change the service, it is possible to make this change only in the class we created. We can adapt our method without the need to look through the entire code to change every reference from the old library to the new one.

Exploring third-party code

When we want to add a new library to our code, we need to understand what it does and how it works. Using code we don't understand in production can cause some problems.

The best way to find out the behavior of a library we want to add is to write tests for situations that we want the library to solve and get them passed. This way we can not only figure out how the code works, but these tests can be useful for any version or a library change.

If you change the version and run the tests, you will find out which behaviors no longer work and correct them.

If I can summarize the use of third party libraries in your code in some topics, they would be:

Maintain a clear separation of third party code and yours.
Write good tests to see if the third party lib will behave the way that makes sense for your code. It is important to note that you are testing your code, not the library.
Make sure that our code has no contact with third party codes. It is better to depend on something you control than something you do not control.
Encapsulate and create adapters so that our code refers to it as little as possible, and that we can swap the library in case of any problems.

Organizing your tests

The biggest concern we have when writing a test should be its readability.

In test code, readability may be even more important than production code.

When writing a test we should avoid writing details that are not part of it so that the person who needs to (re)fix this test in the future knows what is happening without the need to understand unnecessary code.

Use one assert per test

Ideally, you only have one assert per test, so there is no doubt which part of the test has broken when this happens.

This rule could result in many repeated tests. To solve this, you can use before with the code block that repeats.

If there is too much repetition, we may even use more than one assert per test, but very carefully to keep the number of asserts small.

Or, giving my opinion - not Uncle Bob - you may not solve this problem, since too much DRY can impair code readability, and readability should always be your priority when it comes to testing.

Perhaps a better rule is that each test should only test one concept.

It is very important that there is not more than one test at a time to keep it concise, and you can keep track of what is happening.

Uncle Bob uses an acronym to help to remember the rules of a clean test.

F.I.R.S.T

Fast: Tests should be fast. If they take too long, we won't want to run the tests.
Independent: A test should never depend on another to run. It should be possible to run all the tests randomly without breaking.
Repeatable: A test should run in any environment, whether it is QA, Production or in a computer in your house.
Self-validating: The test result should always be a boolean, informing if it passes or not.
Timely: They have a right time to be written, which is before production code. If you leave it for later, you may find the test too difficult to write and not test (TDD).

Organizing your classes.

In java, the order that a class should be organized is this:

Variables list.
Public static constants.
Private static variables.
Instance private variables.
Public Functions.
Private functions called by public functions should be immediately below the calling public function.

In Ruby and other languages, however, all private methods must be grouped and written after all public code. Ideally, they follow the order they were called by public methods.

Classes should be small.

When we say that a function must be small, we say that it must have a few lines.

When we say that a class must be small, we mean that it must follow the principle of single responsibility.

But how do we know if a class has too many responsibilities?

The first sign that a class has too many responsibilities is its name.

Classes should be named in an explanatory way so that we can understand what they do. If you need an "and", an "or", an "if" and a "but", they are already doing more than one thing.

In the example below we can see that the SuperDashboard class looks for the last focused component and changes the build version, thus having two responsibilities.

public class SuperDashboard {
  public Component getLastFocusedComponent();
  public int getMajorVersionNumber();
  public int getMinorVersionNumber();
  public int getBuildNumber();
}

One way to solve this problem is to create a class for each responsibility.

Some people complain that when we have many classes, it's hard to find what we want.

But when we stop to think that if we have a class with many things, we will also have difficulty finding what we are looking for. When we have many classes, it is as if we have several drawers labeled with their contents. But when we have just a few classes we have few stuffed drawers.

A little about cohesion

In an ideal world, the functions inside classes should speak only with the variables created in that class, but as this is impossible, we need our classes to be cohesive.

New classes as a result of refactoring.

We can observe the existence of a flow when we are refactoring a code, which can result in the creation of more classes:

When we break a large function into several smaller ones, we feel the need to share variables.
We want to create class instance variables so that functions don't need parameters, but why do we create instance variables that the minority of functions will use? That doesn't look very interesting.
Is this not an indication that new classes could be created? : D

Organizing a class for changes.

We need to remember that a class must follow the "open-closed" principle, being open to extension and closed to change.

Sometimes our class encapsulates a third-party library that is constantly changing. When this happens, we can solve this with a parent class to connect to the library, and create multiple child classes with the new library implementations as they happen.

post image from Sarah Dorweiler

Identifying the dirt in our code - formatting, objects and data structures and how to handle errors

Rachel Curioso :D — Mon, 07 Oct 2019 12:56:22 +0000

This post is the second in a series of 3 about clean code.

We will talk about code formating, object and data structure, and how to handle errors.

I know that some of those things may seem silly, but a lot of interesting things are discussed within these topics.

In formating I talk, among other things, about the best order for your functions and variables. When I talk about object and data structure, I talk about how you protect the inside of your object. And about errors, I talk about prepare your code to deal with problems when they happen.

In the first post I talked about names, functions and comments I advise you to read (: (Or not! You are not obliged! Rebel!)

The intention is to finish the series in the next post, talking about how to work with third-party code, how to organize your unit test and, finally, how to organize better your classes.

Let's Go

Formatting

When we look at a code that doesn't have good formatting, the first impression is that all code is not very good, and we end up not taking it seriously.

When the subject is formatting, we look not only at the indentation but also at how code blocks are organized.

We can divide the subject formatting into two parts: Vertical formatting and horizontal formatting.

Vertical Formatting

A newspaper story begins with a good headline that tells the reader what the story is about. The first paragraph is the equivalent of a synopsis, so you can get an idea of the tone of the story and as you read it, you'll discover more details.

A good code should be like that too. The module name should be clear so people know what it is about, soon after comes higher-level concepts along with algorithms, and as the code unfolds, there should come lower-level functions with the source code details.

Ideally, the code should be divided into modules, with a space between each module, and they should follow an order, for the code to tell a story.

First, the variables must be declared and then the dependent functions. The only thing that shouldn't follow this rule are functions that have a conceptual affinity.

In the example below, I show the order that functions should be called, and when I speak of functions that have a conceptual affinity, I speak of chocolate? and not_chocolate?

(People, focus on the order that the functions appear and not the names)

something
somewhere = some_place

def ice_cream
  banana(something_1)
  cheese(something_2)
end

def banana(something_3)
  return "something" if chocolate?(something_3)
  avocado(something_3)
end

def chocolate?(something_4)
  #some code
end

def chocolate?(something_4)
  #Another code
end

def avocado(something_5)
  #One more code
end

def cheese(something_6)
  #One more of another code
end

Still talking about the order in which things appear in code, remember that loop control variables are declared within the loop itself:

for(var i = 0; i > something; i++)

Horizontal

It's a good practice to avoid very long lines of code. Some people like to use a limit of 80 characters, others 100, and that's fine, but over 120 characters may be a sign of carelessness.

Another good practice is to group things that we don't want to separate and not separate things that we want to group together. It seems obvious to say so, but sometimes this is not what happens:

in the expression def something(args) we want that something and (args) to be together because they are the same thing. If we put a space between them, def something (args), we get an idea that they are different things.

In int something = another_something we are talking that something and another_something are different things, and when we write int something=another_something, we lose a little of this distinction.

Another important thing to note about horizontal formatting is how we align our variables.

Somethime we feel the need to align this way:

private Socket        socket;
private InputStream   input;
private OutputStream  output;
private Request       request;
private Response      response;
private boolean       hasError;
private long          requestParsingTimeLimit;
private long          requestedProgress;

But we have three problems when we do this:

We take away the intention of what matters. In the example above, we end up not looking for the type of the variable. We only look at your name
Usually, if we use the editor tools to format our code, it takes all these spaces, and we lost our formatting
If we realize that we should align the variables, it's a sign that we have too many variables and, probably, we can divide what we have in more pieces.

This the most appropriate way to align the variables:

private Socket socket;
private InputStream input;
private OutputStream output;
private Request request;
private Response Response;
private boolean hasError;
private long requestParsingTimeLimit;
private long requestedProgress;

Objects and data structure

If we like private variables, why we always write getters and setters in our code? How to handle access to our classes?

Data Abstraction

When we use a method or a class, we don't need to know how they are implemented. What interests us is their returns.

In the example below, we can see the difference between a class with public variables and an interface with various access policies.

public class Point(){
  public double x;
  public double y;
}

The interface with various access policies:

public interface Point(){
  double getX();
  double getY();
  void setCartesian (double x, double y);
  double getR();
  double getTheta();
  void setPolar(double r, double theta);
}

Notice that on the second example, we don't have any method like setX or setY. If we want to create a point, we need to pass both like a couple, using setCartesian.

The first example forces us to deal with each variable separately, even though they are a couple.

Hide the implementation it's not only a matter of hiding variables. It's a matter of abstraction. A class is not just a tangle of getters and setters. They manipulate data and that should be their essence.

Data Structure or Objects?

Objects hide behind abstractions, and its public functions serve to manipulate their data.

As a counterpoint, in data structures, everything is exposed.

class Square < Shape
  Point top_and_left
  side
end

class Circle < Shape
  Point center
  radius;
end

class Geometry
  PI = 3.141592

  def area(geometric_form)
    if geometric_form.is_a?(Square)
      # calculate the area of a square
    elsif geometric_form.is_a?(Circle)
      # calculate the area of a circle using PI
    end
  end
end

In the example above, we have a data structure with this problem:

Any new shape that we want to create, we need to go to the Geometry class and add one more if to the area function.

In this particular case, we could use inheritance to implement the area function in each object, not the Geometry class.

In Object Orientation, it's easy to create new classes without modifying functions, but on the other hand, it's difficult to add new functions in Object Orientated Programming (OOP), as this impacts all the child classes.

Occasionally, it's more important to add new functions than to create child classes. In such cases, don't be afraid to use procedural code.

The important is not to mix data structure with objects, because in that case, we would have the worst of both worlds. The result is structured that are hard to inherit, and difficult to modify existing functions.

The law of Demeter

The law of Demeter states that a module must not know the inside of the module it handles.

A method shouldn't invoke methods or objects of another class.

Looking at the example bellow:

final String outputDir = ctxt.getOptions().getScratchDir().getAbsolutePath();

If ctxt was an object, to access getAbsolutePath() it would need the getOptions() return in order to work. That is, the functions are dependent on each other in order to function.

We could solve this problem this way:

Options opts = ctxt.getOptions();
File scracthDir = opts.getScratchDir();
final String outputDir = stracthDir.getAbsolutePath();

However, we should be aware that if the example above were a data structure, it wouldn't be a problem.

first_name = full_name.to_downcase.split(" ").first

The first example given, we have an information access problem and we have a violation of Demeter's law. But in the example above, we are transforming a piece of information, and there is no problem with this.

Data transfer

When we talk about data transfer, we are referring to objects that have only one variable, but no method.

Some people like to leave all attributes private, and access them through getters and setters.

The only real advantage in this is to makes the code more object-oriented, and ready for possible growth.

public class Person{
  private String name;
  private int age;

  public Person (String name, int age){
    this.name = name;
    this.age = age;
  }

  public getName(){
    return name;
  }

  public getAge(){
    return age;
  }
}

Active Record

The active record works as direct database translations. Usually, they are Data Transfer Objects with some navigational methods like save or find.

It turns out that when we try to add business rules and make it more robust, we end up creating a hybrid structure, half object, half data structure that, as we saw above, is always bad.

The solution to this problem is to treat the Active Record as a data structure and create separate objects that have business rules and other internal data.

Error Handling

Dealing with error is important, but when error handling leaves logic obscure and confusing, it is being done wrong.

In the old days, people tried to check for all kinds of mistakes at once, and that brought many problems besides those mentioned above.

Another problem in this approach is that you need to think in all scenarios before writing code, which not only impairs readability, but it is easy to forget about handling the error later:

if ("scenery 01")
  #...
elsif ("scenery 02")
#(...)
elsif ("scenery 234334134134")
  #...
end

In the example above, it would be interesting to encapsulate the code with a more generic error handling, but clear enough that you can find the root of the problem. For example, if you have a class that fetches users on another system via HTTP, and you have an HTTP error, you don't want to have a generic HTTP exception, but an exception that says you couldn't find the user.

When we throw exceptions, we need to be careful to make the messages clear so that you, the developer, know how to identify the problem after it occurs.

Remember that not every error is an exception. Many errors can be treated as normal code flow. Well done logging is often better than throwing an exception.

One tip to writing error-handling code is to write your try-catch first.

Think that all that is inside the try-catch block should be independent and decoupled from the rest of the application, because if that piece of code goes wrong, probably we don't want to broke everything else.

Writing the try-catch block first helps to make it independent.

It is important to note that not all places need exception handling: those most in need are those where there is uncertainty about the outside world, such as network connections, database interactions, etc.

Another point that needs to be raised is knowing where in the stack you will want to leave the error. The higher above the stack and closer to the user, the better, because the farther from the interaction layer you leave, the harder it is to find the error. However, leaving it close to the user is different from popping the error for the user to see. Sometimes we don't want the user to know what went wrong, but we always need to know what the user did to make such an error happen.

This is a very long topic that would make a book

A preview about dealing with someone else's code

When we use third-party code, it is best not to treat its errors directly in your code.

The ideal is to encapsulate this lib in a class of its own and handle the error inside.

Null/Nil

When we work with null in our code, we create a difficult problem to debug.

When something goes wrong, it throws a generic exception, informing us that something wrong is not right. This exception is so generic that finding its root is very difficult.

Sometimes we need to check if something doesn't exist and we are tempted to verify if something == null. In this case, look to see if there are no other ways of checking. Probably there is a way.

If it's a list, we can verify if the list is empty. If it's a String, we can verify if it's blank and so on.

And, the most important, don't pass null as an argument. When we do this, the chances of receiving a null pointer exception (and equivalents) are much greater.

cover image by Jazmin Quaynor

Identifying the dirt in our code - names, functions, and comments

Rachel Curioso :D — Sun, 29 Sep 2019 00:17:21 +0000

The problem of having code that is not very clean is that, as we maintain it, the code will get more and more complex and its understanding become compromised.

When I talk about complex code, I don't mean business rules, but the complexity of understanding and code legibility. I'm talking about spending some time trying to understand what is p or what the read(p, i)function do when you don't have any context. What does it read? what are p and i? Aaaaahhh /o\

When we are in a place that we spend more time trying to understand an old code than thinking on the new code implementation, it could be a sign that something could be better. Spending more time in a task than we liked to, leave us frustrated

When is difficult to maintain code, we stop to care about its quality and consequently we write "bad" code. We leave the code even more complex and, the more complex it gets, and more difficult it is to maintain. Our productivity drops almost to 0 and it becomes risky to fix a problem without developing 3 more on this process. We become afraid to touch a code that already works "magically" (because we, obviously don't have a clue about what's happening)

The consequences of this are code so difficult to maintain that companies end up closing. I've seen it happen once. The only product had several bugs, it was impossible to fix a bug without creating a few more and the customer satisfaction has reached a level that they didn't want use the product anymore, and the company closed

If we know that is so harmful, why we do this?

Hurry.

Usually, we have such tight deadlines that we deliver our tasks poorly to skip to the next.

I want to avoid this from happening. How I do this?

This is the first part of a series about clean code. The idea, in this first topic, is talk about naming things, write better functions and a little about comments.

Next, I intend to talk about formatting, objects and data structures, how to handle errors, about boundaries (how to deal with another's one code), unit testing and how to organize your class better.

I know that it'll be missing an important topic about code smells, but this is a huge topic that has the potential for another series.

So, let's begin?

Give good names!

Use names that show what your code does:

int d could be int days

instead while x == 7, we could use while time == DAYS_OF_WEEK.

Avoid misinformation.

if accountsList is not a list, it should have a better name.

Varible that has very subtle name differences also fall in this topic, such as
VeryNiceControllerToDealWithStrings and VeryNiceControllerToStoreStrings.

How long did you take to spot the difference between the two variables?

Make a good distinction of your variables.

If we have two variables, one called banana e another called theBanana, how can we differentiate which one is which? This same rule applies for CustomerData, Costumer and CostumerInfo. What's the difference between then?

Use names that you can pronounce

It facilitates internal team communication. If you pair, you don't need to refer to a variable as wpdw. A workDaysPerWeek sounds better (:

Use searchable names

Have you ever tried to use ctrl+f on a variable that you couldn't remember the name? Or that it was so common that you just couldn't? Have you tried to search for a variable called f?

Avoid prefixes!

It's another thing that makes the search difficult. Not only the search but mainly autocomplete. if the variables start with icsd, like icsd_name or icsd_date we'll have a hard time to find what we are looking for.

Avoid mind mapping

When we use a huge quantity of variables that don't make much sense, we need to memorize what they are meanwhile we are trying to figure out what the code does.

user.each do |u|
  u.each do |s|
    s.each do |h|
      print h.name
    end
  end
end

(this code block has another problem with so much each inside each inside each insi.... but we'll talk about that later)

Class names

Should be nouns, and not verbs, because classes represent concrete objects. They are the representation of things.

Methods names

Should be verbs, and not nouns, because methods represent actions that objects must do.

Add context!

If you bump on a variable state alone, probably will have a hard time to figure out what it means.

But if this variable is near street and number it's easier to understand what it does.

Add context, but not for free.

Let's suppose that we are working on a project called chocolate ice cream. We don't need to add CIC in front of all variables.

At the same time, inside a User class, we don't need to call all the variables userAdress, userAge or userFavoriteColor.

Functions

They should be small

They should be small and readable, with few nests. In the ideal world, they should be 1 or 2 levels of indentation.

Do only one thing.

They should make only one thing and that's it.

But how do I know that it does only one thing?

def verifyNameAndLogout
  if rightName?
    showMessage
  end

  logout
end

If you look at the code, it seems that it does 3 things

Verify if the name is right
If yes, it displays a message
logout, regardless the name is right or wrong.

We understand that it does what is proposed in only one level inside the function, so we can say that this function do only one thing.

The only modification that we could do in this code would be relocating the if statement to another function, but in this case, it would be only a relocation, without any additional advantage

Functions can't be divided into sections. If you can divide, it's a sign that it could be more than one function

One abstraction level per function

When we talk about abstraction levels, we can classify the code in 3 levels:

high: getAdress
medium: inactiveUsers = Users.findInactives
low: .split(" ")

The ideal is not to mix the abstraction levels in only one function. When we mix, the function becomes a little harder to understand, and we can't read the code step by step, from top to bottom, like an article

The best scenario is that you can read code from top to bottom, like a narrative.

ex:

To include the setup and the teardown, we first include the setups, then we include the page content, and after that, the teardown.
To include the setup, we add the setup suite and then the default setup.
To include the test setup, we search for the hierarchy...

(and so on...)

Avoid switch statements and excessive if/else

The motive that we should avoid extensive switch/if-else is that beside them beeing to big and doing many things, they violate the open-closed principle of object-oriented programing or. also known as the O in S.O.L.I.D .

One entity should be closed for modification and open for expansion. When I talk about entity, I mean class, module, function and so on

When there are several if/else/switch in a single module, we have to modify the code if we want to add any extra case, what makes the code more fragile and difficult to test.

Sometimes we need to verify differents situations and take different actions depending on the situation.

One way to decrease the switch/if/else is to use polymorphism.

Using a simple example:

foreach (var animal in zoo) {
  switch (typeof(animal)) {
    case "dog":
      echo animal.bark();
      break;

    case "cat":
      echo animal.meow();
      break;
  }
}

this could be refactored in this way:

foreach (var animal in zoo) {
  echo animal.speak();
}

On this example, under the hood, we created an animal class, that has the method speak. Then we created a dog and a cat object, we give then the behavior to speak and that's it.

Sometime, polymorphism could be a little too much to solve this problem. Sometimes we rearrange the logic, create a few more function and fix our problem.

Less arguments is the way to go

When we talk about arguments, Less is more

When we have many arguments, the complexity of our function and, consequently, our tests greatly increases.

Another thing that happens is mistaking the argument order when we call the function.

Occasionally we can decrease the argument size creating a class.

A function with several arguments could be transformed in a class, and this function could be a method in this class. The arguments, much of the time, could be their properties and, this way, we don't need to pass any argument.

In some cases, we don't need this much, so we could use other ways to decrease the number of arguments, like grouping then.

Circle makeCircle(double x, double y, double radius) could be transformed in Circle makeCircle(Point center, double radius)

Function are verbs, arguments nouns

When we name function as verbs, and arguments as nouns, it becomes more legible and easier to understand the behavior that we expect, like write(name)

The argument order is also important so you don't forget when you'll use the function.

Just imagine to get the order right if the arguments were changed: assertExpectedEqualsActual(expected, actual)

Avoid flag as arguments.

Avoid passing a boolean as an argument, because it makes the refactor hard.

Try to verify the truth or falseness when you call the function, and not inside it.

A function shouldn't have collateral effects.

If we have a function called checkPassword, it shouldn't do a login inside its body.

We were not prepared to login at any time and this could cause undesirable side effects, besides test de function becomes more difficult.

Output arguments

Output functions should be avoided. If a function needs to change the state of something, it should change the object.

Sometimes we bump into functions like appendFooter(s) and we are not sure if the argument is an input (s is the footer and we are attaching it somewhere?) or output (we will attach s to the footer?).

If the first case is the correct one, if s is the footer, the best thing to do is objectInstance.appendFooter

Command Query Separation

A function should change the state of an object, or return some info about it.

This is an example of a function that doesn't follow the command Query Separation:

if name?
  name.change
  true
else
  false
end

A function that changes something and returns true or false should be replaced by two. One that verifies, and another that makes the change.

DRY - Don't repeat yourself

The problem with repeated code is, besides that it inflates the code, any change that we need to make we have to change in several places.

However, we must be aware that too much DRY can be harmful. We often confuse code duplication with business rule duplication. Sometimes it's okay to duplicate a code as long as you're not duplicating a business rule that should be unique.

There is another maxim also that says: you must write the same code a maximum of 3 times. The third time you should consider refactoring and reducing duplication.

Avoid returning an error code

When methods return error messages, it violates subtly the Command Query Separation. When we put an error inside an if block, it may cause some confusion, since it may be returning something or an error.

if name?
  name.change
else
  raise 'An error has occured'
end

In the example above, if it works, it performs an action. If it went wrong, it pops a mistake

Comments

Avoid

Comments on a code usually bring more evil than good. Most of the times, a comment about what a variable does, or details of how the things work could:

Become outdated, confusing your future self (Yesterday I lost some precious time because of an outdated comment)
Could be replaced for some better named variable/function/class.
They pollute the code unnecessarily.

It should be clear that avoid != forbid. If you are a java programmer and is doing something public, Javadocs is important. Sometimes it's interesting to explain some code (How many time you spend trying to figure out a regex pattern when you see one?), but, in 99% of the time, comments could be avoided.

How I will write the code if I have to pay attention to all these rules?

In a good article you put the ideas on a paper and goes refining the text. coding functions in the same way.

First, you make it work, then you refactor.

Uncle Bob, in clean code, defends that the best order to write code is:

Write unit tests.
Create code that works.
Refactor to clean the code.

Write all the tests, make it work and, when you are sure that everything is the way that's supposed to be, refactor removing all the dirty code and applying design patterns.

Particularly, I don't have the habit to write tests before the code (TDD), however, test the code before doing a refactoring is indispensable. Only then we can be sure that your code will always work, even after so much modification.

The Clean code book is focused on bad practices. It details several problems and does not delve into ways to solve them.

If you want to delve more into how to fix the dirty-code-problem, we could look into the book refactoring. In this book, there are details and several different ways to eliminate the dirty in the code