Chemaclass - clean-code

Learning Concurrency in Golang

2024-04-02T00:00:00+00:00

I wanted to learn a new language, so after trying some, I ended up with Golang as one of my favorites for its simplicity and capabilities. It has features I haven’t used in years, like multithreading and concurrency.

Golang (or Go) supports concurrency through lightweight threads called goroutines. These are different from traditional multithreading, like in Java, where you have to handle sync and coordination to manage shared resources safely. In contrast, Go’s goroutines are lightweight, managed by the Go runtime, and cheaper to create and manage.

While parallelism is doing several things simultaneously, concurrency is about dealing with several things at the same time. When we talk about concurrency and parallelism, we don’t know the order of things. We don’t know what’s going to happen first or what’s going to end first. There is an undefined order of execution.

Imagine you cooking: preparing a soup, a salad and an omelet. You would be one single unit, but you are preparing different dishes. You might finish the salad first or the soup or the omelet… We cannot guarantee that! This would be concurrency, as you are alone dealing with several things. As soon as your partner comes and helps you cook, then we will be talking about parallelism.

I remember building a similar game in Java when I was learning multithreading ten years ago… let’s use this opportunity to do it again with modern Go.

I built a terminal game emulator that mimics one horse racing. Each horse is a goroutine that runs in a shared bidimensional matrix. Once a horse reaches the end, it notifies the shared channel between all other horses (running in different processes) and they all stop, showing in the terminal the winner of the race.

I separated the code into four areas to help visualize it:

Entry point
Generating the board
Rendering the game
Moving the horses

Entry point #

The struct Horse represents each Horse in the race. The game consists of a list of lines, in which each Horse is running.

type Horse struct {
 Name string // The name of the horse
 Line int // The competition line
}

func (h Horse) Letter() string {
 return fmt.Sprintf("%c", h.Name[0])
}

func (h Horse) Equals(other *Horse) bool {
 return other != nil &&
 h.Line == other.Line &&
 h.Name == other.Name
}

func (h Horse) String() string {
 return fmt.Sprintf("%s (line:%d)", h.Name, h.Line)
}

You can spawn a new process using the keyword go when invoking any function. In this game, this is used 1) to render the game RenderGame() and 2) for each horse’s movement startRuningHorseInLine(). The goal is to keep the “rendering” and “movement logic” working in parallel.

func main() {
 const lines, lineLength = 12, 30

 board := NewRaceBoard(lines, lineLength)
 go RenderGame(board)

 winnerChan := make(chan Horse)
 for line := range board {
 // each horse will be moved in different processes
 go startRunningHorseInLine(board, line, winnerChan)
 }

 // wait until one horse reaches the end
 winner := <-winnerChan
 // render one last time to ensure the latest board state
 RenderRaceBoard(board, &winner)

 fmt.Println("Race finished!")
 fmt.Printf("# Winner: %s\n", winner)
}

Generating the board #

The race board is a bidimensional matrix of pointers to Horses. Each line “contains” only one Horse; aka only one pointer will point to an actual Horse, the rest will be pointers to nil. During the generation of the Board, we will create one Horse at the first position of each line.

func NewRaceBoard(lines, lineLength int) [][]*Horse {
 board := make([][]*Horse, lines)
 for line := range board {
 board[line] = make([]*Horse, lineLength)
 board[line][0] = &Horse{
 Name: generateHorseName(),
 Line: line,
 }
 }
 return board
}

The names are randomly generated using HorseNames.

var HorseNames = [][2]string{
 {"Alloping", "Giggles"},
 {"A-lot", "Gallop"},
 {"BoJack", "Jack"},
 {"Baroness", "Belle"},
 // ...
}

func generateHorseName() string {
 name := HorseNames[rand.Intn(len(HorseNames))][0]
 surname := HorseNames[rand.Intn(len(HorseNames))][1]

 return name + " " + surname
}

Rendering the game #

Then RenderGame(), renderRaceBoard(), renderRaceLine() and renderRacePosition() are separated to help focus on each method’s responsibility, identifying what is the subject to be rendered.

RenderGame() is being executed in another process using go.

func RenderGame(board [][]*Horse) {
 for {
 time.Sleep(renderDelay * time.Millisecond)
 RenderRaceBoard(board, nil)
 }
}

func RenderRaceBoard(board [][]*Horse, winner *Horse) {
 // use a "string buffer" to save the whole board state
 // so we can later use one IO call to render it
 var buffer bytes.Buffer
 buffer.WriteString("\n")
 for line := range board {
 renderRaceLine(board, line, &buffer, winner)
 }
 clearScreen()
 fmt.Println(buffer.String())
}

func clearScreen() {
 cmd := exec.Command("clear")
 cmd.Stdout = os.Stdout
 cmd.Run()
}

func renderRaceLine(
 board [][]*Horse,
 line int,
 buffer *bytes.Buffer,
 winner *Horse,
) {
 buffer.WriteString(fmt.Sprintf(" %.2d | ", line))
 var current Horse
 for col := range board[line] {
 h := renderRacePosition(board, line, col, buffer, winner)
 if h != nil {
 current = *h
 }
 }
 buffer.WriteString(fmt.Sprintf("| %s", current.Name))

 if current.Equals(winner) {
 buffer.WriteString(" [Won!]")
 }
 buffer.WriteString("\n")
}

func renderRacePosition(
 board [][]*Horse,
 line, col int,
 buffer *bytes.Buffer,
 winner *Horse,
) *Horse {
 if board[line][col] == nil {
 buffer.WriteString(" ")
 return nil
 }

 current := board[line][col]

 if current.Equals(winner) {
 removeChars(buffer, col+1)
 for range board[line] {
 buffer.WriteString("-")
 }
 }

 buffer.WriteString(current.Letter())

 return current
}

Moving the horses #

In main(...), the winnerChan is a shared channel that will be used by the first Horse reaching the last position in their line.

Each Horse will run a loop until reaching the end of the line OR receiving (via the shared channel winnerChan) the message that another Horse already won the race. Until then, each horse will move independently by randomly sleeping milliseconds before moving to the next position in their line.

startRuningHorseInLine() runs in another process using go.

func main() {
 //...
 winnerChan := make(chan Horse)
 for line := range board {
 // each horse will be moved in different processes
 go startHorseRunning(board, line, winnerChan)
 }
 // wait until one horse reaches the end
 winner := <-winnerChan
 //...
}

func startRunningHorseInLine(board [][]*Horse, line int, winnerChan chan Horse) {
 for {
 select {
 case <-winnerChan: // check if another horse finished
 return // in such a case, then stop the for loop
 default:
 time.Sleep(time.Millisecond * time.Duration(rand.Intn(maxSleepDelay)))
 moveHorseOnePos(board, line, winnerChan)
 }
 }
}

func moveHorseOnePos(board [][]*Horse, line int, winnerChan chan Horse) {
 cols := len(board[line])
 for col := cols - 1; col > 0; col-- {
 if board[line][col-1] == nil {
 continue
 }
 // here we identify that there is a horse in
 // the following column, so we move it to the
 // current column, and we set `nil` the other one
 board[line][col] = board[line][col-1]
 board[line][col-1] = nil

 if col+1 == cols {
 winnerChan <- *board[line][col]
 }
 break
 }
}

Source code #

The code displayed in this post is a simplified version, so if you would like to check the working source, you can do it here: Chemaclass/go-horse-racing.

Effective Pair Programming

2024-03-28T00:00:00+00:00

What is pair programming? Two people working together on the same problem, at the same time.

It is not about one person showing off their skills in front of another, nor one person afraid of making mistakes due to an impostor syndrome.

Each person will have a role:

Navigator: he will pay attention to the bigger picture; eg: architecture, relation between collaborators, object design, etc.
Driver: she will pay attention to the small details; eg: naming, code conventions, writing syntax, object design, etc.

The pair could, and should, switch roles occasionally; eg: every X commits pushed, every 10 mins, … up to them.

Pair programming should not be considered a practice only for “seniors” to juniors, but regardless of the team members’ experience level.

It is about the collaboration flow, the quality communication, the absence of feeling judged, and the idea of welcoming vulnerability with your peers, knowing they will support and help you.

It is about constantly challenging each other, seeking the most pragmatic solution while keeping it simple. Always looking for quick feedback when speaking to each other, but also on the solution you agreed to implement and its direction.

It is about the short, quick, and immediate feedback loop while talking to your partner, who reviews your code on the fly. You can guide as a navigator or help the driver validate their ideas in a broader picture.

It is about the constant sharing of knowledge atmosphere by default, reducing bus-factors and silo-knowledge areas to the maximum. Increasing the focus by having two minds working on the same task simultaneously.

It is about team cohesion and sharpening the feeling that we belong. When we understand each other’s strengths and weaknesses, we will realize how much we can help each other grow.

How can you practice pair programming? #

Pair programming can be done in different ways:

You can start and finish a task with pairing. You can time-box it to 30, 60, 90 minutes. Either way, it is recommended to have pauses in the middle - Pomodoro.
You can start the task together and stop when one of your peers feels confident enough to continue alone.

It is up to the team, and the task in context, to decide when and how to apply pairing to get the best out of it.

This does not mean you must constantly work “no matter what” in pair. This is not about creating rules; on the contrary, it is about embracing this practice to the point you feel confident to choose when and how to use it to get the best out of it.

Pair programming might become one of the best tools in your team toolbox for daily interactions. Not because you read it somewhere but because of the benefits you and your team will find.

Common Patterns #

Different strategies for effective pairing #

Driver-Navigator: One person is driving the code (with the keyboard), focusing on the detail aspect of the task itself. The other is a navigator (no keyboard), having a more abstract picture of the task in mind.
Ping-Pong: Frequent switching driver-navigator roles in small interactions, e.g., every N minutes, every N commits, etc.
Backseat driver: The navigator engages actively with the driver.
Tourist guide: The navigator passively learns with the driver.

Anti-patterns while pairing #

The silent partner: The navigator is not participating, and they are being silent.
The solo act: The driver ignores all inputs from the navigator.
Distracted pair: The pair does not focus on the problem to solve.
The Dictator: One person is telling what to do, ignoring the input from the other.
Philosophical pair: The pair is bikeshedding into irrelevant topics.
The code war: The pair does not reach an agreement and starts an unnecessary war, which wastes time and effort.

Want more? Check this out: Learning Through KATAS

The takeaway #

Pairing is not a rule to enforce, it is a tool to reach for. Use it when the task is complex, the knowledge is siloed, or the stakes are high. Skip it when the work is trivial. The goal is never “always pair”, it is better software and a stronger team. Pick one real task this week, pair on it, and switch roles often. The benefits show up faster than you expect.

Great Engineering

2023-12-30T00:00:00+00:00

Coding is not just another job. Writing software can be really fun and, even more, it can be your personal hobby as well! You might be focused on coding, coding and more coding to level up your own career skills.

That itself is not bad at all! Practice makes the master, so a lot of coding will inevitably help you improve your coding skills… but there are other aspects that you need to keep in mind in order to help you grow into a great engineer.

As a software engineer, your job is not “just to write software” for its own sake, but to use software to solve actual business problems. To make that happen there are plenty of different methodologies out there, for sure. However, we must agree that you need to identify and understand your customer’s needs in order to know what to actually build.

You need to know your product, at least until certain level, so you can design your software using a similar language closer to the business, which will help its evolution and overall quality. This will be beneficial for the future (and present) maintenance of the product.

IT, Software, Product and People topics are highly interconnected, and having at least a common ground of understanding the relation between these can help the overall goal of every single individual.

The result of a great team work is not equal as the sum of the individual parts, as it’s multiplying the created value among their peers. To that, great communication skills are a key part of it in order to create as much clarity as possible from any different abstraction level.

That’s why a great engineer is a knowledgeable person about business, customer, product, and coding. Understanding these points have a strong impact on your daily work as it creates a difference between the average and the great engineer.

Image original by Nicola Ballotta.

How to Test Private Methods?

2023-10-20T00:00:00+00:00

This is a question that I have encountered with some frequency for a long time. So I thought I would put together my thoughts on the subject here.

Short answer #

Never.

Long answer #

Never ever.

What if…? #

If you really want to test a private method, consider extracting that private method logic into a separate class, and write a unit test for that class’ behavior.

For this one, I was inspired by Fran Iglesias’ original post.

Dedicated QA Teams in Software?

2023-05-17T00:00:00+00:00

This will be controversial, but let’s talk about the QA position. The hidden truth behind the lack of software quality and why this should concern you if you write software.

QA is a role, not a position #

As a software developer, when you write software, you are responsible for the quality of whatever you’re writing. A third person acting like QA could find that your solution doesn’t work like expected, but how come? You might argue they might catch edge cases, but how could that be possible if the software was already tested previously?

A software team’s final goal is to make the QA position useless because they should find nothing but well-working software. But how do you get to that point? How can we ensure that the software we write is working as expected and there is no need for a QA person in our team?

The hidden truth behind the lack of software quality #

Unfortunately, in our software industry, the demand for “fast, quick and dirty” projects ended up in poorly developed MVPs by simply applying patches and code over code with just manual testing checking happy paths, sometimes even ignoring edge cases.

“The deadline is in one week, so you better finish it on time!”

We don’t learn the importance of what automated testing can bring to our daily job, so we don’t take it seriously, and therefore, we don’t practice it enough. And, for that exact reason, because we don’t practice it, we don’t know how to perform it properly. Yes, I am talking about writing automated tests that prove the behavior of your software!

Our inability to write testable code results in software that is hard to test, and thus we delegate testing to other third parties shifting the responsibility for the overall end quality of the product or service we write.

Practice makes the master #

You must learn and apply proper testing techniques when they make sense. How and when effectively use test doubles, prepare solitary or sociable tests, which compromises and reasons backup your mind when choosing one or other paths toward your testing strategies?

You are the latest and main responsible person in charge of your knowledge, so you better invest in yourself because no one else will do it for you.

Look at everything you do as an opportunity for learning. Practice and get better by default at everything you do.

If you don’t know how to start, here is my favourite tip: you can always practice and improve your testing skills using code-katas. Read more about this topic here.

Nice theory, but… why bother? #

Manual testing is, of course, necessary. It is another testing strategy that I am not blaming or attacking. We might still need a dedicated person in charge of discovering what new features we want to build to satisfy our clients. But this blog-post is not about that position.

It is all about shortening the feedback loop. If you can write software to work in specific ways, can’t you write automated tests to prove that the software you wrote behaves the way you expect?

If you have covered with automated tests the behavior of your software at any level that makes sense, what’s left for a dedicated QA person?

Next time you think about “We need a QA person to test this,” try the exercise of thinking instead, “How can I write an automated test that verifies what I would expect if a QA person were checking this?”

And that’s how you change the “full-time QA position” into a “role mentality for everyone that writes software.”

Code never lies and never forgets; once it’s written and automated in your pipeline, you can run it anytime at zero cost.

Recipes for Decoupling

2022-11-28T00:00:00+00:00

What is coupling, and why is it bad? What is decoupling, and how to do it efficiently? This book is a compilation of strategies to decouple your domain code from those infrastructure details, so you can enjoy a healthier system in the long run.

This book will teach you how to create PHPStan rules from no knowledge, and then it will guide you across many decoupling opportunities like, for example:

web framework
cli frameworks
form validation
orm and database
test framework

Read more about the book: matthiasnoback.nl/book/recipes-for-decoupling/

Buy it here: leanpub.com/recipes-for-decoupling

Different Beliefs About Software Quality

2022-10-08T00:00:00+00:00

I recently got a great question on Twitter which got me thinking for a while and I decided to share my thoughts about it.

The tweet that started this #

But first, some context: I am feeling great because the codebase where I work is getting better and better, so I am tweeting this:

“As software improves with time, you can feel you’re doing right.”

And then I got a question asking for suggestions:

So there we go…

My answer #

Create agreements #

The first thing is to create agreements about what quality software means for your team and yourself. This helps clarify what software culture you want to establish and work towards that direction. Leaving your company should be the last resort once you have no other option.

Before thinking about leaving your company, I would ask you:

Why do you think you cannot improve the working codebase of your company?
What can you do to reduce the friction between your different beliefs regarding what quality means for software?

There is no perfect codebase to work on because software is a living entity and constantly changes. So, at least for me, quality software is the one that can cope with change smoothly.

Once you have agreed on that goal, and while there are multiple ways to achieve that result, my favorite way of working is keeping an agile mindset with doses of extreme programming values, principles, and practices in mind.

Software is about people #

Software is not just about writing clean and solid code. This is indeed desired, and we should aim for that, but we must first understand why we want that. The “why” is based on the values that you have as a team.

If you don’t share the same purpose, the same “why,” then you won’t enjoy working together, and in such a case, I would advise looking for another company that shares your values. But, before that, I would strongly suggest fixing the deeper issue and helping your team improve.

Understanding your why #

You first need to deeply understand your “why” so you can transmit this to your peers and the people around you. Have you tried all you can to create awareness about your “why”?

Some ideas include encouraging collaborative programming (pair/mob), presenting some internal tech talks, creating a culture of sharing knowledge on a regular daily basis, creating awareness about the current status quo, and looking for opportunities to improve everywhere.

Your career path #

If, after several months of (really) trying these ideas, none of them work, look for a new company that shares your beliefs. After all, you’re the first and primary responsible person for taking care of your career path.

Original twitter thread.

Extra thoughts #

If you want something to be different, don’t wait till it’s changed automatically. Try to change it; if it’s not working, leave it. Maybe you don’t belong in that place.

On the other hand, it’s crucial to reflect if you see that pattern often repeating (changing companies too quickly). In such a case, maybe the problem isn’t the companies but yourself.

Software development is not just about code but business. It’s essential to be aware of finding a fair trade-off between speed, costs, and quality, depending on the situation. You might want to use some tech debt to conquer the market as soon as possible.

It doesn’t make sense to have “low quality” as part of the identity of any team. Every team has certain quality expectations. Therefore, the key here is to agree on what good quality is.

Clean Craftsmanship

2022-07-11T00:00:00+00:00

The book is divided into three parts: the disciplines, the standards, and the ethics.

The 1st part is the most technical one. It guides you with TDD examples, showing how testing can help you to design your code.

The 2nd part is about productivity, quality, and courage.

The 3rd part is about how did we get here in terms of people who develop software, and our responsibility within our ethics about do no harm, integrity, and teamwork.

One of my favourite parts from the book:

Our software industry is wildly dynamic and changing; therefore, we must all be continuously aggressive learners.

How and when do you do this learning? If your employer provides you the time and space to do this kind of learning, then take as much advantage of it as you can. If your employer is not helpful, then you’ll have to learn on your own time.

Be prepared to spend several hours per month on it. Make sure you have the personal time set aside for it.

Yes, I know you have family obligations, bills to pay, planes to catch, and you’ve got a life. Okay, but you also have a profession. And professions need care and maintenance. I expect us all to be continuous aggressive learners.

Chapter 11. Courage - Continuous Aggressive Learning

Index #

Part I: The Disciplines #

Chapter 1. Craftsmanship #

Extreme Programming
Test-Driven Development
Refactoring
Simple Design
Collaborative Programming
Acceptance Tests

Chapter 2. Test-Driven Development #

Overview
The Basics

Chapter 3. Advanced TDD #

Getting Stuck
Arrange, Act, Assert
Test Doubles
Architecture

Chapter 4. Test Design #

Testing Databases
Testing GUIs
Test Patterns
Test-Specific Subclass
Humble Object
Test Design
Breaking the Correspondence

Chapter 5. Refactoring #

What Is Refactoring?
The Basic Toolkit
Extract Method
The Disciplines

Chapter 6. Simple Design #

YAGNI
Covered by Tests
Coverage
Design?
Maximize Expression
The Underlying Abstraction
Minimize Duplication
Minimize Size

Chapter 7. Collaborative Programming #

Chapter 8. Acceptance Tests #

The Discipline
The Continuous Build

Part II: The Standards #

Chapter 9. Productivity #

We Will Never Ship S**T
Inexpensive Adaptability
We Will Always Be Ready
Stable Productivity

Chapter 10. Quality #

Continuous Improvement
Fearless Competence
Extreme Quality
We Will Not Dump on QA
QA Will Find Nothing
Test Automation
Automated Testing and User Interfaces
Testing the User Interface

Chapter 11. Courage #

We Cover for Each Other
Honest Estimates
You Must Say NO
Continuous Aggressive Learning
Mentoring

Part III: The Ethics #

The First Programmer
Seventy-Five Years
Nerds and Saviors
Role Models and Villains
We Rule the World
Catastrophes
The Oath

Chapter 12. Harm #

First, Do No Harm
Best Work
Repeatable Proof

Chapter 13. Integrity #

Small Cycles
Relentless Improvement
Maintain High Productivity

Chapter 14. Teamwork #

Work as a Team
Estimate Honestly and Fairly
Respect
Never Stop Learning

I found this chat in YouTube where Uncle Bob talks about most of the topics form his book Clean Craftsmanship.

Listen out for:
* Quote & Intro - [00:00:00]
* Career Journey - [00:07:29]
* Clean Craftsmanship - [00:10:53]
* Programmer as a Profession - [00:15:31]
* Craftsmanship - [00:18:45]
* Disciplines - [00:22:45]
* Disciplines: Test-Driven Development - [00:28:49]
* Disciplines: Refactoring - [00:34:31]
* Code Coverage - [00:39:02]
* Standard: Never Ship S**t - [00:42:35]
* Standard: Always Be Ready - [00:47:15]
* Ethics: Do No Harm - [00:50:00]
* Ethics: Estimate Honestly - [00:53:56]
* 2 Tech Lead Wisdom - [00:57:50]

The Path to Seniority in Software

2022-06-08T00:00:00+00:00

We all have been junior developers at some point. This is easy to know because it sits at the very beginning of your career. Your responsibilities were narrowed down by other peers who were looking after you.

At some point, after months or years, you got your promotion or another job, where you weren’t a junior anymore, but an intermediate.

An intermediate (also known as middle) is something between junior and senior. You know now that you are not a junior anymore, you know how to deliver value but yet you also have mixed feelings about seniority. You want to be a senior, but you don’t know how. There is no clear path to achieving this goal.

Wait for a second… there are actually two easy ways to get the senior title! You can get promoted as such in your company, or you can start a new position as a “senior” in another company, easy right?

Marketing and politics #

Unfortunately, the “seniority” level is very much polluted by marketing and politics. First, what does it mean “senior” in this context? In all the companies where I have been working (if not all) I have always been surrounded by people who claimed to be “seniors” when in reality only a few I would consider such.

Our senior label is inflated by companies needing experts on paper more than in reality, and this is a problem we need to deal with and speak about.

Seniority generally means more experience, but how do you calculate this? It is easy from a company’s point of view: more years in the industry. But, is the number of years you have been working really relevant in an industry that is constantly changing and evolving? Actually, this wouldn’t be a big issue if you have the software fundamentals well interiorized, but funny enough, I have seen these fundamentals in only ~10% of the seniors I have met across many years and several companies.

The fact that you have been working for 10 or more years doesn’t necessarily mean you are a “senior” with software. What else can we measure in order to identify if you deserve indeed this title?

It is not all about the money #

Let us be honest, senior titles are better paid than junior or middle positions. If you have the chance to get a higher salary because you got the “senior” in your job title, well, it wouldn’t be clever to reject it. But, independently of politics and marketing, we must address some seniority fundamentals to understand better what the word “senior” means in this context.

It is not all about the money, but also about the responsibilities that come with seniority.

Seniority fundamentals #

Being senior in our software industry is not about “the number of years of experience” but:

How well do you transmit your knowledge to others? Sharing what you know is a core task for a senior person.
How well do you collaborate with other people, including the PM/PO and other teams? Collaboration is crucial to creating a constant feedback loop.
How well do you work together with your peers? Pair-programming builds team cohesion and helps everyone become better.
How strong are your testing skills? Testing is tied to the quality of your work, and a senior should aim for an incremental design.
How well do you understand delivering value constantly in small chunks? The sooner you deliver value, the sooner you get feedback about it.
How deep is your technical knowledge of quality software and the trade-offs to get there? SOLID principles, clean code, TDD, refactoring as part of your daily job, low coupling, high cohesion, appropriate data structures, and choosing the right solution (KISS, YAGNI…).
How well do you adapt and cope with change? Change is inevitable, so we must learn to deal with it, especially the parts we cannot control.
How developed is your entrepreneurial thinking? Always keeping the organization’s goals in mind.

As you can see, there is no mention of concrete technology or years of experience. Why? Because technology is just an “implementation detail”, and experience comes by practicing and attitude, not by letting the time pass by.

Attitude is important #

We’ve got two persons:

A) a person who is working for 15 years, doing relatively the same every day, and without caring about his own skills. He just does what others tell him to do.

B) a person who is working for 5 years, challenging herself every week, trying different approaches when dealing with problems, and sharpening her own skills constantly.

Can you see the main difference? No, it’s not the 10 years difference of “experience” between them, but their attitude.

We wrongly understand that a year of experience must come with learning and knowledge, so we tend to use time as a measurement of seniority. But I argue that the “attitude factor” is equal or even more important. I have been surrounded by many people who call themselves seniors with 3, 6, 10, and more years of “experience” but lacking attitude, and you could clearly see this problem on a daily basis.

You need this combination to build yourself as a truly senior developer; time, experience, and most importantly: attitude towards improving your own skills and the ones that surround you.

Where to start #

Seniority is not granted, it is practiced. You don’t wait for the title, you build the behavior until the title catches up. Start small, and start now:

Teach what you know. Pick one thing you understand and explain it to someone this week. If you can’t explain it, you don’t own it yet.
Seek the uncomfortable. Volunteer for the task slightly beyond you. Growth lives at the edge of what you can already do.
Reflect on purpose. After each project, ask what you would do differently. Experience without reflection is just repetition.

The path is not a promotion. It is the daily decision to improve yourself and the people around you. Do that long enough, and the title becomes a formality.

To Mock or Not to Mock

2021-01-11T00:00:00+00:00

Mocking is useful, but “what to mock” usually turns out to be more complicated than expected if you don’t treat this carefully.

How to escape the mocking hell #

What is actually happening when we create a mock? Which types of mocks are there? Is mocking good or bad? Well, as always, everything depends on the context. And here we will consider some of the main situations about when to mock and when not to mock, but especially why.

What happens when you mock something? #

First, we should define what is a mock:

In a unit test, mock objects can simulate the behavior of complex, real objects and are therefore useful when it is impractical or impossible to incorporate a real object into a unit test.

Mocking makes sense in a unit testing context. An integration test should go through the real implementation checking the integration between multiple units, which are even allowed to talk to the DB or File IO: infrastructure code. Therefore we should agree that a unit test is a fast and deterministic test that doesn’t rely on external dependencies and doesn’t require any special context to run.

Mock objects meet the interface requirements. In consequence, they allow us to write and unit-test functionality without calling complex underlying or collaborating classes.

A mock is a test double that stands in for real implementation code during the unit testing process. It is also capable of producing assertions about how it was manipulated by the test subject during the test run.

I strongly recommend you to read this post if you want to get into the details of why Mocking is a code smell (Topics like these: What is a mock? What is a unit test? What is test coverage? What is tight coupling? What causes tight coupling? What does composition have to do with mocking? How do we remove coupling? and more!)

The problem with mocking #

When you mock you are overriding the logic of the mocked class. The real logic is getting hidden behind the scenes and there is actually where bugs love to live. Consider that:

The mock may have attributes, methods, or arguments that the real object doesn’t.
The mock’s return values may differ from the real objects’ return values. For example, it may return a different type of object that has different attributes.
The mock’s side effects and behavior may differ from the real objects’ ones. For example, maybe the mock fails to raise an exception when the real object would raise it.

Alternatives to mocking #

“Are you saying that mocking is bad and we shouldn’t mock?!” No.

It depends on what you are “overriding”.

Is your business domain logic what you are mocking? Then it’s wrong.
Is the connection to the DB what you are mocking? Then it’s right.

It depends on the context of the logic and where that logic belongs.

Is it part of your business domain logic? Then you shouldn’t mock it but instantiate it.

Is it part of any infrastructure dependency like DB connection, IO file system, Network, or any external service that has nothing to do directly with your business domain? Then mock it using abstractions/interfaces.

The interface should be the contract between your business domain logic and its external infrastructure dependencies. Imagine how easy it would be to unit test your domain logic by instantiating it and calling their methods with different arguments expecting different inputs under your entire control.

Some tricks #

When you are writing a unit test:

Try to instantiate your classes first.
Avoid mocking concrete classes. I wrote an article exclusively about this: encouraging final classes and interfaces.

Mock interfaces. Instantiate concrete classes.

“Excessive use of mocks leads to legacy code.” - Philippe Boargau

How can we avoid excessive mocking? #

Favor immutable state over a mutable state.
Make dependencies explicit.
Program to an interface, not to an implementation.

References #

Mocking is a code smell - Eric Elliott
When to mock & Test Definitions - Uncle Bob
Final classes by default - Matthias Noback
The problem with mocks - Sean Hammond
A Set of Unit Testing Rules - Michael Feathers

Principles of package design

2020-11-12T00:00:00+00:00

Apply design principles to your classes, preparing them for reuse. You will use package design principles to create packages that are just right in terms of cohesion and coupling, and are user- and maintainer-friendly at the same time.

The first part of this book walks you through the five SOLID principles that will help you improve the design of your classes. The second part introduces you to the best practices of package design, and covers both package cohesion principles and package coupling principles. Cohesion principles show you which classes should be put together in a package, when to split packages, and if a combination of classes may be considered a “package” in the first place. Package coupling principles help you choose the right dependencies and prevent wrong directions in the dependency graph of your packages.

What You’ll Learn #

Apply the SOLID principles of class design
Determine if classes belong in the same package
Know whether it is safe for packages to depend on each other

Never Use array_merge in a Loop

2020-11-10T00:00:00+00:00

Using array_merge inside a loop is a performance killer. The spread operator will help you to improve this by flatting the array.

Flattening a one-level array #

I have seen people using the array_merge function in a loop like:

<?php
$lists = [
 [1, 2],
 [3, 4],
 [5, 6],
];
$merged = [];
foreach($lists as $list) {
 $merged = array_merge($merged, $list);
}
// $merged === [1, 2, 3, 4, 5, 6];

This is a very bad practice because it’s a (memory) performance killer! Instead, you should use the spread operator (in PHP since 5.6!):

<?php
$lists = [
 [1, 2],
 [3, 4],
 [5, 6],
];
$merged = array_merge(...$lists);
// === [1, 2, 3, 4, 5, 6];

Unpacking an assoc-array #

What if you had an assoc-array instead like this one?

<?php
$lists = [
 'key-1' => [1, 2],
 'key-2' => [3, 4],
 'key-3' => [5, 6],
];

In that case, you will need to unpack its values:

<?php
$merged = array_merge(...array_values($lists));
// === [1, 2, 3, 4, 5, 6];

In Functional Programming, this is known as flatting a list. No loops & no more performance problem.

Flatting a multilevel array #

What if you wanted to flat a multilevel array like this one?

<?php
$lists = [[1], 2, [[3, 4], 5], [[[]]], [[[6]]], 7, 8, []];

Or like this one, even with key-values?

<?php
$lists = [
 'key-1' => [
 1,
 [2],
 'key-2' => [
 3,
 [
 'key-3' => [4, 5],
 ],
 ],
 ],
 6,
 'key-4' => [7, 8],
];

In these cases, you might want to use the internal standard library:

<?php
$merged = iterator_to_array(
 new RecursiveIteratorIterator(
 new RecursiveArrayIterator($lists)
 ),
 $use_keys = false
);
// $merged === [1, 2, 3, 4, 5, 6, 7, 8];

Which flattening approach to reach for #

Usually, being aware of how to flat a “2 level” array might be sufficient:

<?php
$flattenList = array_merge(...array_values($lists));

Otherwise, the internal standard library will help you deal with it.

References #

Typed Arrays in PHP

2020-10-13T00:00:00+00:00

Argument unpacking, function variable argument list, and variadics function.

The perfect combination #

Argument unpacking: Instead of passing the argument itself to the function, the elements it contains will be passed (as individual arguments).
Function variable argument list: The arguments will be passed into the given variable as an array.
Variadics function: Types can be checked with a type-hint.

We will use this snippet for our examples. Having a class, Customer:

<?php
/** 
 * @psalm-immutable 
 */
final class Customer
{
 // Using PHP 8 constructor property promotion
 // https://wiki.php.net/rfc/constructor_promotion
 public function __construct(
 public string $name,
 ) {}
}
// We create a list of 6 customers
$customers = array_map(
 fn(int $i): Customer => new Customer("name-{$i}"),
 range(1, 6)
);

Whenever we want to manipulate a list of Customers, we can pass as an argument: …$customers.

How we used to do it #

We define the array type using the PHPDoc param comment block above. But we cannot define the real type of the item. The code will still run without any problem passing any type on that argument array $customers:

<?php
/** 
 * @param Customer[] 
 */
function createInvoiceForCustomers(array $customers): void
{
 foreach ($customers as $customer) {
 // ... some irrelevant logic for this example
 }
}

The code below would work at “compile-time”. But it might fail at “runtime”.

<?php
createInvoiceForCustomers($customers);
createInvoiceForCustomers([new Customer('any name')]);
createInvoiceForCustomers([new AnyOtherType()]);

An alternative (recommended!) might be to extract that logic and ask for the particular type in order to “check it” at runtime in that particular moment, failing if one of the items wasn’t really a Customer:

<?php
/** 
 * @param Customer[] 
 */
function createInvoiceForCustomers(array $customers): void
{
 foreach ($customers as $customer) {
 createInvoice($customer);
 }
}
function createInvoice(Customer $customer): void
{
 // ... some irrelevant logic for this example
}

Everything here below would work at “compile-time”. It will for sure break during “runtime” if the createInvoice(Customer $customer) receives something different than a Customer.

<?php
createInvoiceForCustomers($customers);
createInvoiceForCustomers([new Customer('any name')]);
createInvoiceForCustomers([new AnyOtherType()]); // won't work

By doing that createInvoice(Customer $customer) we are ensuring the type of the argument, which is good! But, what about going one step further. Could we check the types of the elements when calling the function createInvoiceForCustomers(array $customers), even making the IDE complain when the types are not right?

Well, that’s actually what Generics are for, but sadly, they are not yet in PHP. Not even in the upcoming PHP 8. Hopefully in a near future, but we cannot predict that for now. Luckily, we have currently an alternative nowadays, but it’s not that popular. It has its own “pros” and “cons”, so let’s take a look at an example first:

<?php
function createInvoiceForCustomers(Customer ...$customers): void
{
 foreach ($customers as $customer) {
 createInvoice($customer);
 }
}

Everything here below would work at “compile-time”. It will for sure break during “runtime” if the createInvoice() receives something different than a Customer.

<?php
createInvoiceForCustomers(...$customers); // OK
createInvoiceForCustomers(
 new Customer('any name'), 
 new Customer('any name'),
); // OK
// This is not even possible to write. The IDE will yell at you. 
// It's expecting a `Customer`, but `AnyOtherType` is given:
createInvoiceForCustomers(new AnyOtherType());

PROS #

We can easily type a list of any concrete type.

CONS #

We better define our functions with one or two arguments max. Otherwise, it would be too complicated to read.

Important remarks #

It needs to be the last taken argument of a function.
It helps to minimize the number of arguments that we use in a function.

Variadics simulate typed arrays, use them wisely #

Argument unpacking is a great feature that, in combination with variadic functions, can help us to simulate typed arrays. With great power comes great responsibility, and this is no exception. We need to learn about our toolbox in order to use it wisely.

References #

Object design style guide

2020-10-10T00:00:00+00:00

Objects are the central concept of languages like Java, Python, C#. Applying best practices for object design means that your code will be easy to read, write, and maintain.

This book captures dozens of techniques for creating pro-quality OO code that can stand the test of time.

Examples are in an instantly-familiar pseudocode, teaching techniques you can apply to any OO language, from C++ to PHP.

Testing Effectively Legacy Code

2020-08-17T00:00:00+00:00

These tests are also known as Characterization tests.

A characterization test describes the actual behavior of an existing piece of software, and therefore protects existing behavior of legacy code against unintended changes via automated testing. This term was coined by Michael Feathers.

They enable and provide a safety net for extending and refactoring code that does not have adequate tests. A test can be written that asserts that the output of the legacy code matches the observed result for the given inputs.

How to start? #

These are my learnings one year after reading Working Effectively with Legacy Code and applying it to the different projects I’ve been working on since then.

1. What do you want to test? #

Find out the assertions. Create a test file for your class, and a testing method for the function that you want to test. Hint:

If you have the following method applySomeLogic(): ReturnType,
the test you could write is test_apply_some_logic(): void.

final class MyBusinessLogic
{
 private DependencyInterface dependencyInterface;
 private ConcreteDependency concrete;

 public function __construct(
 DependencyInterface dependencyInterface,
 ConcreteDependency concrete
 ) {
 this.dependencyInterface = dependencyInterface;
 this.concrete = concrete;
 }

 public function applySomeLogic(Input input): ReturnType
 {
 // black box responsible to create a ReturnType
 // based on the given Input
 return returnType;
 }
}

final class MyBusinessLogicTest extends TestCase
{
 public function test_apply_some_logic(): void
 {
 // I want to assert that "applying some logic"
 // from MyBusinessLogic with the given Input
 // I will receive a concrete ReturnType with a 
 // certain value as its property. Something like:
 
 returnType = myBusinessLogic.applySomeLogic(input);
 assertEquals('expected', returnType.getProperty());
 }
}

2. Instantiate the concrete/final class that you want to test. #

Do not mock your concrete classes. Especially your business domain. Mock only interfaces. Otherwise, you can be hiding bugs unintentionally (with green/passing tests!). Treat your business domain classes as final.

Either mock the interface or instantiate an anonymous class if you want to create a Stub:

Stubs provide answers to calls made during the test, usually not responding to anything outside what’s programmed in for the test.

final class MyBusinessLogicTest extends TestCase
{
 public function test_apply_some_logic(): void
 {
 myBusinessLogic = new MyBusinessLogic(
 this.createMock(DependencyInterface.class),
 new ConcreteDependency(/* ... */)
 );
 // OR
 myBusinessLogic = new MyBusinessLogic(
 new FakeDependency(),
 new ConcreteDependency(/* ... */)
 );
 // ...
 }
}

Where FakeDependency is a concrete implementation of DependencyInterface with already “fake data/implementation” that it’s useful only for testing purposes.

3. Call the method from that class providing the desired input. #

The output will be determined by the initial state of the business logic class that we want to test PLUS the input arguments that we are using.

input = new Input(/* ... */);
returnType = myBusinessLogic.applySomeLogic(input);

4. Assert the output with the expected value. #

From step-1 you need to know what you want. Apply the assertion(s) now.

final class MyBusinessLogicTest extends TestCase
{
 public function test_apply_some_logic(): void
 {
 myBusinessLogic = new MyBusinessLogic(
 this.createMock(DependencyInterface::class),
 new ConcreteDependency(/* ... */)
 );

 input = new Input(/* ... */);
 returnType = myBusinessLogic.applySomeLogic(input);
 assertEquals('expected', returnType.getProperty());
 }
}

5. You might want to assert different expected values. #

You can easily provide different arguments to your business logic either via the logic construction or different given arguments. To do so, use the @dataProvider annotation. The “dataProvider” method must be public and return any iterable.

final class MyBusinessLogicTest extends TestCase
{
 /** @dataProvider providerApplySomeLogic */
 public function test_apply_some_logic(
 array concreteMapping,
 string argInput,
 string expectedValue
 ): void {
 myBusinessLogic = new MyBusinessLogic(
 this.createMock(DependencyInterface.class),
 new ConcreteDependency(concreteMapping),
 /* ... */
 );

 input = new Input(argInput, /* ... */);

 actual = myBusinessLogic.applySomeLogic(input);
 assertEquals($expectedValue, actual.getProperty());
 }

 public function providerApplySomeLogic(): Generator
 {
 yield [
 'concreteMapping' => ['key' => 'value'],
 'argInput' => 'something',
 'expectedValue' => 'expected-value-A',
 ];

 yield [
 'concreteMapping' => ['key2' => 'value2'],
 'argInput' => 'something-else',
 'expectedValue' => 'expected-value-B',
 ];
 }
}

Lastly: clean what you did. #

Yes, clean the tests. They deserve to be as clean as your production code. Otherwise, they will rot as time passes by and remain dirty for your colleagues and your future self!

For example, you can apply extract method refactoring to move out the implementation details (of the creation of the different objects) and keep the same abstraction level while reading the test code.

myBusinessLogic = this.createBusinessLogic(concreteMapping);
input = this.createInput(argInput);
actual = myBusinessLogic.applySomeLogic(input);
assertEquals(expectedValue, actual.getProperty());

Of course, everything depends on the context. Does it really make sense to extract into a private method the createBusinessLogic() or even createInput()? Well, that’s up to you. It depends on the number of lines and, most importantly, the abstraction level that belongs to that context.

Just remember: keep your methods small.

Now you can refactor the production code that you covered with tests without that fear of breaking it.

All together #

Legacy Code is code without tests #

Of course, there is way more to learn about testing and working with legacy code. In fact, especially when dealing with legacy code, you will encounter situations where the code is coupled somehow that you might want to mock your concrete classes because there is no interface (yet) for it.

This book presents to you a lot of techniques about when, why, where, and how you can apply these changes.

When working with code you need feedback. Automated feedback is the best. Thus, this is the first thing you need to do: write the tests.

First, add tests, then do your changes. #

Change as little code as possible to get tests in place with the recipe: #

Identify “change points” to break your code dependencies.
Break dependencies.
Write the tests.
Make your changes.
Refactor.

Strict Types in PHP

2020-08-09T00:00:00+00:00

In December 2015, PHP 7 introduced scalar type declarations and with it the strict types flag. What is this new feature?

The good thing about declaring a PHP file as strict is that it actually applies to ONLY the current file. It ensures that this file has strict types, but it doesn’t apply to any other file in the whole project. It allows you to do, step by step, this migration from non-strict code to strict code, especially for new files or projects.

To enable the strict mode, a single declare directive must be placed at the top of the file. This means that the strictness of typing for scalars is configured on a per-file basis. This directive not only affects the type declarations of parameters, but also a function’s return type.

Strict types affect coercion types #

Using a type hint without strict_types may lead to subtle bugs.

Without this, int $x meant $x must have a value coercible to an int. Any value that could be coerced to an int would pass the hint type, including:

a proper int (example: 42 -> 42)
a float (example: 13.1459 -> 13)
a bool (example: true -> 1)
a null (example: null -> 0)
a string with leading digits (example: “15 Trees” -> 15)

By setting strict_types=1, you tell the engine that int $x means $x must only be an int proper, no type coercion allowed. You have the great assurance you’re getting exactly and only what was given, without any conversion or potential loss.

Who should care about this “strict type” line? #

Actually, declare(strict_types=1); is more for the reader than for the writer. Why? Because it will explicitly tell the reader:

The types in this current scope (file/class) are treated strictly.

‘strict_types=1’ is more for the reader than for the writer

The writer just needs to maintain such strictness while writing the expected behavior. That said, as a writer, you should care about your readers, which also includes your future self. Because you are going to be one of them.

References #

The Art of Refactoring

2020-06-28T00:00:00+00:00

If you see something, in the scope of your current task, that can be easily improved, improve it. And if you have any questions about it, ask.

What is refactoring? #

Refactoring means improving your code. It can go from making a variable name more readable, extract some lines of code into a private method, or separate the responsibilities of a class into subclasses, for example.

Refactoring is the action of showing that you care about what you do as a professional. It can be a controversial topic; it is indeed one of the major controversial topics since a long time ago. But we shouldn’t stop trying our best in order to improve the quality of the system just because of that controversiality.

When and how should we refactor? #

Always. In the scope of your current task unless it is an already planned task, something like “architecture refactoring” or similar, where the scope of the task is actually to do refactoring.

Refactoring should be part of our daily job, not a separate task by default.

We do not need to ask permission to refactor. Or do we ask our managers for permission to do our best job?

In order to do proper refactoring, the intention of such refactoring needs to be clear. What is intended to achieve and how? Pair programming (or even pair thinking!) certainly helps in this topic because it syncs two brains on the same topic and that encourages team building and a better understanding of them.

Applying refactoring in a collaborative way, in a “bidirectional channel”, is fundamental when working within a team. Refactoring shouldn’t be a taboo topic, on the contrary: it will be helpful in order to unify the goals and the direction of the team code quality.

Some personal advice about the “how” #

Continuous improvement is what we’re looking for within this topic, but…

If you realize your changes are generating more noise than help, stop immediately and think again if your changes are worth it in the current system status.

Maybe it’s not the right moment for that refactoring.

Maybe you are polluting your current diff with out-scoped changes.

Or, maybe, your refactoring idea is too big to be applied in your current task. In such a case, a follow-up task (in order to apply the refactoring) would be a better idea.

If you see that refactoring is perhaps needed even before starting your current task, do the refactoring first.

We usually refactor in order to increase our productivity, making the code more readable and therefore easier to understand.

Testing #

Be aware that you should have a pretty good suite of tests covering the logic that you might have changed. Without tests, refactoring can be really risky. Usually, the easier something is to be tested, the easier it is to be replaced or removed.

You can read more about how testing is related to quality here.

Why should we do it? #

Wouldn’t you want to have a better system as time goes by?

Software isn’t like wine: it doesn’t get better as time passes by. Therefore, if you want to have a better system you must work for it.

Final Classes in PHP | Java | Any

2020-06-06T00:00:00+00:00

Clear contracts, isolated side effects, testability, low complexity and cognitive load, code fluidity, and confidence in yourself.

Motivation #

Reduce the scope visibility to the minimum #

When you see a class prefixed with final you will prevent a particular class to be extended by any other, which not only makes it more readable but also makes you be sure that the scope of the logic where you are is limited to that particular class.

Encourage “composition over inheritance” mentality #

The Open-Close Principle states: open for extension but closed for modification.

If for any reason, a good one you should be completely aware of, you decide to create an inheritance there, well, then just drop the final keyword and you are good to go.

When you “by default” can’t extend from a class (because it’s final), you will help yourself by thinking about using composition instead of inheritance.

Why isn’t this class final? #

If we aim for composition over inheritance, then we should try to avoid inheritance as much as possible, and use it only when it’s really necessary. Inheritance is often misused in OOP.

Misconception #

When we first taught OOP, we usually introduced the classic inheritance example.

Nonetheless, when Alan Kay created Smalltalk, the inheritance was never the main concept of it. The main concept was messaging, which is that you can send messages to objects and they encapsulate the data and logic in it, and you can change their behavior by using different objects, which is actually composition. But the concept of inheritance is so popular that it eventually overshadows composition.

Benefits #

Clear contracts. Using interfaces will force you to think in terms of communication between objects.
Isolated, side effect free code units. Injecting interfaces only as dependencies will remove every nasty side effect around the code you are working on.
Testability. Mocking dependencies is extremely easy when they are interfaces.
Low, manageable complexity. Since everything is isolated, you won’t need to worry about rippling changes. This dramatically decreases the complexity of your code.
Low cognitive load. With decreased complexity, your brain will be free to focus on what matters.
Code fluidity. By removing any unnecessary coupling, you will be able to move things around way more easily than before.
Confidence in yourself. Being able to test your code in isolation so well will give you a wonderful sense of confidence in changing it.

Composition over inheritance #

If you feel the need to reconfigure an object, to change parts of an algorithm, or to rewrite part of the implementation, consider creating a new class instead of overriding an existing class. If you need to represent a hierarchy of classes, where subclasses are proper substitutes for their parent classes. This would be the classic situation where you may still consider inheritance. However, the result may even be better if you don’t inherit from concrete parent classes but from abstract interfaces.

What you should start doing instead #

Use interfaces to define the contracts between your classes.
Use final classes to implement behavior for those interfaces.
Use composition (using dependency injection through constructor) to put things together and prevent complexity.

Interfaces -> Final classes -> Composition

The Art of Testing: Where Design Meets Quality

2020-04-07T00:00:00+00:00

Why you should consider testing as part of your daily development habit and how it’s directly linked to the software quality.

This post intends not to explain the different testing techniques that we can use. I’m not going to tell you the differences between unit, integration, feature, or end-to-end testing.

I’m still amazed by the lack of experience with testing in software in general. Common ignorance in this world about best testing practices for us as developers. Inexperience that you can easily see if you have already worked on different projects and teams.

Software testing #

Some horrible patterns I’ve seen (and done):

Testing for the sake of testing: testing every single file, sometimes wrongly considered a unit.
Mocking every class we intend to test, overriding the actual implementation, and creating a fake behavior, providing a false coverage perception.
Coupling production code with tests everywhere, so it’s impossible to change anything without breaking some tests, even if the feature itself it’s working as intended.
Not testing at all because “why should we even test anything if the feature is done, and it works? Why should we spend more time on this if it’s done?.”

One of the main reasons for software testing is actually verifying a suite of proofs for the expected behavior of the final software piece. However, testing can (and should) be more than that.

Software design #

Software design goes from algorithm to architecture design. Even when I believe these two levels of components have different needs and requirements, they still share some common patterns. For example, testing, and this is what we are going to talk about right now:

If it’s easy to test, it will likely be because of good design.

Software quality #

Is quality hard to measure out? Indeed. There are different measurement keys that we should take while considering quality for any piece of software. Still, I’m sure we could agree on this:

If you aim for quality in your software, you better seek a good design.

Testing by itself means “proving,” as we all know. That said… how difficult it sometimes turns to prove some logic that we finally give up because of its complexity itself?

The art of testing is about using testing itself to help and contribute to the final result. To encourage good design, suppose we’re able to use testing (of any kind) in our favor, depending on the context of what we want to prove. In that case, it will undoubtedly help us increase the product’s end quality.

Therefore, testing should be used not only to prove the behavior of our software but also to guide our software to a better design.

Should we test everything? Well, that’s the million-dollar question. In my opinion, everything depends on the context. We might encounter situations where tests might not be beneficial. Even in those situations, we should write our code as if it could be tested anyway.

Testable code tends to better design and, therefore, better quality.

Clean Architecture

2018-06-04T00:00:00+00:00

Code design principles (SOLID) #

Single Responsibility: a class should have one, and only one, reason to change. Or the new version: a module should be responsible to one, and only one, actor.
Open-closed: a class should be open for extension but closed for modification.
Liskov’s Substitution: objects in a program should be replaceable with instances of their subtypes without altering the correctness of that program.
Interface Segregation: many client-specific interfaces are better than one general-purpose interface.
Dependency Inversion : one should depend upon abstractions, not concretions.

Component principles #

Component cohesion #

Reuse/Release Equivalence Principle: classes and modules (i.e. a component) reused together should be released together. They should have the same version number and there should be proper documentation such as changelogs.
Common Closure Principle: classes that change together should be grouped together, and vice versa. The single responsibility principle at component-level.
Common Reuse Principle: don’t force users of a component to depend on things they don’t need. The Interface Segregation Principle at component-level.

Component coupling #

Acyclic Dependencies Principle: no cycle in the dependency graph. Cycles couple components and, among other things, force them to be to released together. Use the dependency inversion principle to break cycles.
The Stable Dependency Principle: less stable components should depend on more stable components. Depend on the direction of stability.
Stable Abstractions Principle: stable components should be abstract, and vice versa. An example of an abstract stable component is a high-level policy which is changed by extension following the open-closed principle.

Architecture principles #

Setting boundaries #

Boundaries are lines that separate software elements. They separate things that matter from things that don’t, i.e. high-level components from low-level components. If a high-level component depends on a low-level component at the source level, changes in the low-level components will spread to the high-level component. Therefore, we place a boundary between the two, using polymorphism to invert the logic flow. This is the Dependency Inversion Principle in the SOLID principles.

Separating layers #

We can identify four main layers, although the number may vary:

Entities: objects containing critical business logic. For example, a bank could establish that no loans are granted to customers not satisfying some credit score requirements. Entities may be shared across apps in the same enterprise.
Use-cases: app-specific business rules. For example, the sequence of screens to execute a bank transfer.
Interface adapters: Gateways, presenters and controllers. For example, this layer will contain the MVC architecture of the GUI and also objects that transform data between the format of the database and the use-cases.
Frameworks and drivers: web frameworks, database, the view of MVC.

The Pragmatic Programmer

2016-10-01T00:00:00+00:00

Takeaways #

Don’t Repeat Yourself.
Mindset is as important as knowledge.
Good code is easier to change than bad design.
Choose great tools and become fluent with them.

Don’t Repeat Yourself (DRY) #

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.
DRY is about the duplication of knowledge, of intent. It’s about expressing the same thing in two different places, possibly in two totally different ways.

Mindset is as important as knowledge #

Some important aspects of this mindset include:

Taking responsibility for your work by not making excuses or passing blame when things go wrong.
Writing software that’s good enough. This means not wasting time on things that are better than they need to be to make the product successful.
Not ignoring technical debt. The authors use the analogy of broken windows:

Don’t leave “broken windows” (bad designs, wrong decisions, or poor code) unrepaired. Fix each one as soon as it is discovered. If there is insufficient time to fix it properly, then board it up. Perhaps you can comment out the offending code, or display a “Not Implemented” message, or substitute dummy data instead.

The Clean Coder

2016-08-01T00:00:00+00:00

Programmers who endure and succeed amidst swirling uncertainty and nonstop pressure share a common attribute: They care deeply about the practice of creating software. They treat it as a craft. They are professionals.

Readers will learn #

What it means to behave as a true software craftsman
How to deal with conflict, tight schedules, and unreasonable managers
How to get into the flow of coding, and get past writer’s block
How to handle unrelenting pressure and avoid burnout
How to combine enduring attitudes with new development paradigms
How to manage your time, and avoid blind alleys, marshes, bogs, and swamps
How to foster environments where programmers and teams can thrive
When to say No and how to say it
When to say Yes and what yes really means

Summary #

Chapter 1: Professionalism #

Being a professional means taking full responsibility for one’s actions.
First rule is not doing harm to the function nor the structure of the software.
You will always make occasional mistakes, but you must learn from each.
You should be certain about all code you release and firmly expect QA to find nothing wrong with it.
- Test it and test it again.
- Automate your tests.
- Design your code to be easy to test.
You should follow the Boy Scout rule and always leave a module a little cleaner than you found it so that it becomes easier to change over time, not harder.
Your career is your responsibility, not your boss nor your employers.
- Spending 20 hours a week beyond your normal work to improve your knowledge and skills.
- Read, experiment, practice (kata), talk to other, collaborate, look over the fence, mentor.
- It should be fun.
Also, know your domain, identify with your customer (no “us vs. them”, ever).

Chapter 2: Saying No #

Professionals have the courage to say no to their managers.
Managers and developers have roles that are often adversarial, because on the short term, their goals tend to conflict.
The higher the stakes, the more valuable a “no” becomes, and the harder to say.
Good teams will successfully work towards a yes, but only a right yes, that will later work out in practice.

Chapter 3: Saying Yes #

There are three parts to making a commitment:
- You say you will do it
- You mean it
- You actually do it
Your commitment must respect the limits of what you expect (based on your experience) you can and cannot do.
- If you recognize you will probably not be able to meet a commitment, you need to raise a red flag immediately.

Chapter 4: Coding #

Programming requires a level of focus that few other disciplines require.
“The zone” (or “flow”) is not as good as people think: you will be locally productive, but will often lose the bigger picture and possibly product not-so-good designs.
Interruptions are bad distractions.
- Pair programming is helpful to cope with them.
- TDD helps to make the pre-interruption context reproducible.
  - Minimize time spent debugging
Coding is a marathon, not a sprint, so conserve the energy and creativity.
Leave when it’s time, even in the middle of something important.
Continuously re-estimate your best/likely/worst completion time and speak up as soon as you recognize you will likely be late.
- Do not allow anyone to rush you.
- Use a proper definition of “done”, with sufficiently high quality requirements.
Programming is too hard for anyone, so get help and provide help to others, in particular (but not only) in mentoring style.
- Don’t be shy from asking.

Chapter 5: Test-Driven Development #

TDD is not a cure-all and is impractical or inappropriate in some (rare) cases.
TDD Cycle:
1. Add a test
2. Run all tests. The new test should fail for expected reasons
3. Write the simplest code that passes the new test
4. All tests should now pass
5. Refactor as needed
6. Repeat

Chapter 6: Practicing #

A programming Kata is a precise set of choreographed keystrokes and mouse movements that simulates the solving of some programming problem.
- A Kata is about the process, not the solution.
- You aren’t solving the problem because you already know the solution.

Chapter 7: Acceptance Testings #

Avoid garbage in, garbage out. Make sure you understand the requirements.
- Creating this understanding means removing ambiguity.
The best way to do this is defining acceptance tests:
- All customer’s conditions need to be fulfilled by automated tests to prove the expected software behavior.
- Success of those tests constitutes the definition of “Done”.
Code implementation should start only when the tests are complete.
Unlike unit tests (which are only for programmers), the audience of acceptance tests are both: business and developers.
Run all tests in a continuous integration and immediately fix any failures.

Chapter 8: Test Strategies #

Consider QA part of the team. They act as specifiers: writing acceptance tests, including the failure cases and corner cases, and perform exploratory testing.
Testing pyramid:
- Most tests are unit tests. By developer and for developers.
- Many tests are component or integration tests. By QA or Business assisted by Developers. For Business and Developers.

Chapter 9: Time management #

Management roles in software development requires good time management.
Meeting are necessary but are also often huge time wasters, so avoid meeting that have no clear benefit <- this is a professional obligation.
Meeting must have an agenda and a clear goal.
- Agile stand up meetings can be an efficient format.
- Iteration planning should take 5% of the iteration.
Concentration (focus) is a scarce resource.
- Use it well when present and recharge with simpler tasks (meetings) and breaks in between.
- How to improve?
  - Sport.
  - Creative input.
  - Short breaks every 45 minutes.

Chapter 10: Estimation #

Estimation is the source of most distrust between business people and developers because the latter provide estimate which the former treats like commitments.
- Both are insufficiently aware that the estimate really is a probability distribution, not a fixed number.

Chapter 11: Pressure #

The professional developer is calm and decisive under pressure, adhering to his training and disciplines, knowing that they are the best way to meet pressing deadlines and commitments.
Avoid situations that cause pressure via:
- make only commitments you can fulfill
- keep your code clean
- work in such a way that you need not change it when in crisis
Don’t panic. Talk with your team. Don’t rush. Trust your disciplines.
Offer to pair to others in crisis.

Chapter 12: Collaboration #

Not all but most programmers like working alone. But we need to understand the goals of the surrounding people, including business folks.
- This requires communication.
Likewise, within the development team: only collective code ownership and pairing produce a good level of communication.
- Programming is all about communication.

Chapter 13: Teams and Projects #

Teams need time (months) to gel, to really get to know each other and learn to truly work together.
- Assigning fractional people to different projects is a bad idea, as is breaking up a good team at the end of a project.
- Instead, assigning several projects to one team can work well.

Chapter 14: Mentoring, Apprenticeship and Craftsmanship #

Young programmers need mentoring.
- Mentoring can be implicit or explicit.
Given that we entrust software with all aspects of our lives, a reasonable period of training and supervised practice would be appropriate.

In this lesson, Uncle Bob demonstrates the need to write a clean code and establishes the bases to achieve it, being these bases of a social and scientific nature. Making it clear that the future of programming is based on an ethical and polite code.

In this second lesson, Uncle Bob teaches us the purpose of comments in the code, breaking the paradigm that commenting is something “I have to do” for the simple fact that we mistakenly consider that commenting is a good practice. For Uncle Bob, writing a comment is a sign of failure, since a good code must be able explain by itself: Fewer Comments = Better Code.

In this third lesson, Uncle Bob focuses on raising awareness, given the need to increase the level of criteria in code production. Pointing to the lack of preparation in most programmers, as one of the main reasons for the inefficiency in software development today.

In this fourth lesson, Uncle Bob introduces us to a software development methodology oriented through testing. This is the Test-Driven Development (TDD), a practice with a long learning curve, but with significant results to generate a more robust, safer, more maintainable code and with greater development efficiency.

97 Things Every Programmer Should Know

2016-07-15T00:00:00+00:00

Tap into the wisdom of experts to learn what every programmer should know, no matter what language you use. With the 97 short and extremely useful tips for programmers in this book, you’ll expand your skills by adopting new approaches to old problems, learning appropriate best practices, and honing your craft through sound advice.

My main key takeaways #

01.- Pay off technical debt as soon as possible.

02.- Learn and master functional programming.

It makes your code less prone to error and easier to debug.

03.- Don’t guess what a user would do; get users to do things and watch them.

04.- Automate coding standards.

05.- Write simple code, simple descriptive names, simple relationships.

06.- Before you refactor: consider the existing tests and code.

Work in increments, make sure the tests still pass after every change.

08.- Always leave code cleaner than you found it, even if you didn’t write it.

10.- Choose your libraries/frameworks carefully to avoid unnecessary complexity.

11.- Make your code easy to understand using domain terms.

13.- The layout of the code is also important.

14.- Use code reviews focusing on knowledge-sharing among team members.

15.- Objects immutable whenever relevant. Each variable should have the smallest possible scope. Never include more than four function arguments.

18.- Take responsibility for your own education and never stop learning.

That can be done with just a bit of time each week and there are many ways to go about it (e.g. podcasts, lessons, books, etc.).

19.- When designing an API, aim to make it easy to use, not convenient to code.

20.- Deploy early and often. Do not leave it until the end of the project.

22.- Improving your skills should be on your daily basis.

23.- Adapt the technical level of your domain-specific language to your audience.

24.- Don’t be afraid to break things if that’s what’s necessary to fix things.

25.- Careful with your test data because that might go public accidentally.

26.- Handle your errors as they appear, don’t leave it for later.

27.- Learn different programming languages.

Learn their own “culture” or way of doing things.
It’ll make you definitely a better programmer.

28.- Don’t just catch your errors, really handle them.

29.- Understand at least some complexities of your business, not just programming.

30.- DRY: Don’t Repeat Yourself.

32.- Encapsulate behavior, not just state.

33.- Floating point numbers inevitably can create errors in calculations.

34.- Open source is a great opportunity to do interesting work and develop programming skills.

36.- Give proper context when asking for help, because people can’t just guess what’s going on.

37.- It’s not about the long hours. Learn to work effectively.

Dedicate time to continuous learning and to think about what you’re doing.

38.- Write proper bug reports:

Precisely how to reproduce the bug,
how often it appears,
what should have happened,
what actually happened.

39.- Don’t write unnecessary code.

Only write code that adds value and is needed right now.
Remove dead code.

41.- The main cause of delays in application response time is a high number of remote interprocess communications, not the algorithm.

DB connections, for example.

42.- If a compiler warning shows up in your build, fix it.

Don’t leave it for later. Even if it’s not going to be a problem in production.
Compiler == any static code analysis for non compiled languages.

43.- Learning to use command line tools is a valuable educational experience, and you might end up preferring them.

44.- Learn (at least) two different languages and paradigms well.

45.- Invest some time to master the IDE you’re using.

It’ll make your life easier and save you time in the long run.

46.- Know and work with your limitations: budget, resources, time, etc.

47.- Work in small tasks, don’t be afraid to throw away changes.

You’ll still have the insight you gained from the experience.
Know what you need to accomplish beforehand.

48.- Use a relational DB if your application is going to handle a large, persistent, interconnected set of data.

49.- Learn to communicate well in many “languages”: not just to your machine, but also to business partners, and maybe even pick up a foreign language too.

It’s good for connections and for life.

54.- Think twice before implementing “temporary solutions”.

55.- Make GUI easy to use correctly and hard to use incorrectly.

Anticipate errors and find ways to prevent them.
It’s about the user’s experience, not your own.

56.- In projects, find ways to make the invisible visible.

57.- Message passing leads to better scalability in parallel systems.

58.- Write code that other people can easily understand.

59.- Using polymorphism in your classes and objects reduces the need for if/else statements, which results in smaller, safer code.

60.- QA is your friend, not your enemy.

61.- Version your releases.

62.- Make sure your source code clearly states what the program is doing.

63.- Learn about the build process. It’s an important part of development.

64.- Practice pair programming.

65.- Prefer domain-specific types over primitive types.

They make the code more readable and less prone to errors in development.

67.- A professional takes personal responsibility for their career and their code.

68.- Use version control.

69.- Sometimes the best way to solve a problem is to step away from the computer and let the solution magically appear in your mind.

70.- Reading code is a good way to learn. Other people’s or your old code.

72.- Reinventing the wheel is a great way to develop your skills.

75.- If the code you wrote is truly horrifying, don’t try to fix. Delete it and start again.

76.- Apply the Single Responsibility Principle (SRP).

77.- If a client or team member requests a product change, don’t dismiss it outright even if you don’t agree. Ask why instead.

That will lead to a more productive conversation and better results.

78.- If you’re doing the same thing over and over, try to find a way to automate it.

79.- Take advantage of code analysis tools.

80.- Write tests based on the desired functionality of your program, not incidental behavior.

83.- Testing takes time, but it ensures the quality of the end product. Do it.

85.- There are many benefits to collaborative work and pair programming.

86.- Sometimes fixing a mistake in the code leads to uncovering a hidden error.

87.- Write code with other programmers in mind.

88.- Learn to use Unix tools. Learn how to use the terminal.

89.- Use the right algorithm and data structure for the job.

To do that, you need to understand them well.

90.- Have a good logging policy.

91.- Using the DRY principle helps you identify and repair performance bottlenecks.

92.- Testers and programmers should collaborate.

93.- Write code as if you had to support it for the rest of your life.

94.- Try to write “small” functions.

Good tests act as documentation for the code they’re testing.

They describe how the code works.

To be a good programmer, you have to care about the quality of the code.
Really, really discuss things with your customers before assuming you understand what they want.

Clean Code

2016-05-01T00:00:00+00:00

Even bad code can function. But if code isn’t clean, it can bring a development organization to its knees. Every year, countless hours and significant resources are lost because of poorly written code. But it doesn’t have to be that way.

Summary #

Chapter 1: What Is Clean Code? #

The code can be measured with either “good” or “bad” in the code review or by how many minutes it takes you to talk about it.
A clean code should be elegant, efficient, readable, simple, without duplications, and well-written.
You should add value to the business with your code.
Clean code offers quality and understanding when we open the source file.
It is necessary that your code is clean and readable for anyone to find and easily understand. Avoid wasting others’ time.

Chapter 2: Meaningful Names #

Names of the classes, variables, and methods must be meaningful and clearly indicate what a method does or what an attribute is.
Create pronounceable names to facilitate communication.
Avoid acronyms and avoid confusing names, which may bring anyone who reads the code to the wrong conclusions.
Use names that reflect the system domain, the context, and the problems that must be solved.

Chapter 3: Functions #

Methods should be easy to read and understand.
Methods should convey its intention.
Methods should be small.
They must have up to 20 lines.
Methods should only do one thing.
You should use names with words that say what it really does.
The optimal number of parameters of a method is zero, after one and two.
Three should be avoided, but if you think it should be used, have a justification.
Boolean type as a parameter already states that it does more than one thing.
Avoid duplication.

Chapter 4: Comments #

One of the common reasons for comments is because the code is bad.
If you’re thinking about writing a comment, then the code should be refactored.
Comments do not save a bad code.
Try to explain what the code causes happening.
Comments can be useful when placed in certain places.
Don’t explain your code with comments. Use informative vars/method names.
Comments can be used to express the importance of certain points.
Do not write comments with redundant, useless, or false information.
They shouldn’t be used to indicate who changed or why, use versioning.
Don’t comment code that will not be used. Remove it instead.

Chapter 5: Formatting #

Formatting should indicate things of importance since it is a developer of communication form.
A messy code is hard to read.
The readability of the code will take effect on all the changes that will be made.
Smaller classes are easier to understand.
Set a limit of characters per line of code. For example 120.
Try to keep more next related concepts vertically to create a code stream.
Use spaces between operators, parameters, and commas.

Chapter 6: Objects and Data Structure #

Follow the Law of Demeter:
- Each unit should have only limited knowledge about other units: only units “closely” related to the current unit.
- Each unit should only talk to its friends; don’t talk to strangers.
- Only talk to your immediate friends.
Do not make dumb objects.
Objects hide the data abstraction and expose methods that operate the data.
Data structures expose your data and do not have significant methods.

Chapter 7: Error Handling #

Error handling should be planned carefully by all programmers.
When wrong things occur, we have to get it to do the right things.
Give preference to launching an exception than treating it just to hide.
Create messages with information about the error.
Mention that it failed. Where was this failure? If possible, mention why it failed.
Look at separate business rules for errors and error handling.
Avoid returning a NULL in methods, preferably to return an empty object.
Avoid passing NULL to the methods; this can generate NullPointerExceptions.

Chapter 8: Boundary #

In third-party code, to avoid passing objects, APIs look forward in order to keep things in the same class.
Perform tests on the API’s third party.
Study the documentation and test the third API before you start using it.
Check well the features you will use.

Chapter 9: Unit Tests #

Make sure each piece of code is doing what you expect it to do.
Follow the TDDs law:
- Don’t create code before you have a failing test.
- Don’t create more tests than necessary to fail.
- You cannot write more code than enough to pass the test that is failing.
Keep your test clean.
The tests must undergo changes in the same way that the code.
The dirtier the code, the more difficult test will be to maintain.
Use the F.I.R.S.T rule for testing:
- The test is fast-running.
- The tests are independent of others.
- The test is repeatable in various environments.
- The test is self-validating.
- The test is timely.
The test is as important as the production code.

Chapter 10: Classes #

By default, classes should start with the variables:
- Static and constants public.
- Static and variable private.
- Instances and variables privates.
- Soon after comes the functions.
- The class name should represent its responsibility.
The class must have only one responsibility: one reason to change.
You should try to make a brief description of the class.
The methods should be small and one responsibility.

This interview is based on Uncle Bob’s book “Clean Code”. They cover some existing guides that can help you become a better programmer and explore how books and current trends are shaping the software landscape.