Making Good Software

I still remember how naive I was just after I finished my studies. I was convinced that I was ready to join any software company and start shining as a top class developer. Obviously, no long after I started working, I realized how many things I didn’t know.

As I have been acquiring experience, I have been learning things the hard way, stuff which I was never taught, and which its understanding, is basic to become a good developer. This is my list of the 10 things I wish I had been taught.

1.- We’re always wrong.

Developers, among other non technical defects, have quite big egos, that´s why is very hard for us to recognize that we were wrong about something. I’ve seen many endless design discussions where developers will go on and on with their own ideas… well, guess what.. We are all wrong, the only difference between our positions is the degree of wrongness.

Is very important to understand and embrace this fact, only once that we do so we will be open to listen to others and use their own ideas to build a better solution.

2.- If something can break, it will break.

Aka “hope driven development“, if you are not sure about something, if you find yourself using the word “should”, then you are in trouble.

There is only one solution for this, do whatever is necessary to make sure that it doesn’t break, this could mean that you will have to write a test, debug, clarify the requirements…

3.- All code is crap.

After 10 years complaining about all the code that surrounds me, I have come to a brilliant conclusion, all code (including mine), is crap. Of course there are many degrees of crappy code, but even the best code I’ve ever seen is not easy to read.

This doesn’t mean that is not worthy trying to make your code better, all the opposite, there’s a huge difference between the best kind of code and the worst kind of code.

4.- There is always a bug.

ALWAYS! Is just a matter of how hard you look for it.

5.- The most important thing is the client.

Among many things the client doesn’t care are: the technologies you use in the project, how many more things that required the application does… or in general, if you use good practices.

And since I can imagine how much hate comments I will get if I only leave the previous paragraph, let me clarify what I want to say… We should never forget the client perspective, sometimes developers use technologies or insist in over engineering just for the sake of using best practices, but remember, if it doesn’t add any value for the client, drop it.

6.- Design on paper doesn’t work.

I used to believe that I could put my whole design in a paper upfront, and then just fill in the gaps, but it simply doesn’t work.

Software development is complex, is hard to see all the entities and their relationships until you don’t get the hands dirty. So keep planning and designing upfront, it is very helpful, just don’t try too hard, and don’t take the diagrams as contracts.

7.- Less is more.

Or as you probably know it better: “Keep it simple, stupid!” (KISS). So if is not necessary drop it, because remember: “If something can break, will break”.

8.- Coding is only 20% of what we do.

Be ready to spent 80% of your time thinking, debugging, testing, in meetings, conversations… And all of the other activities are very important, so you have to develop a wide range of skills, not only technical, to become a good software developer.

9.- The customer doesn’t know what he/she wants NEVER!.

Customers have a necessity, or an idea, but they don’t know the details… Software development is all about discovering the details and removing all the uncertainty and converting them into an application.

10.- Someone has done it before.

So don’t reinvent the wheel, use Google, or better yet, ask your colleagues, many times they may have done already the same or something very similar.

Bonus: Hey! Our job is cool!

On the bright side, programming is still cool!

After several years developing software, I have acquired a very a strong opinion on how software should be developed, I actually have come to the conclusion that everything boils down to 10 principles, that if well implemented, will make any software development successful.

1.- Customer first.

“If we don’t take care of the customer… somebody else will.”

Customer first means focusing from a customer perspective on real value for the product being developed, other aspects as: contracts, requirements, technologies… should take a secondary role in the project.

Not focusing on the customer in one the top 5 five non technical mistakes made by programmers.

2.- Code quality.

Even though code quality is something very subjective, (all code is crap), it drives many important aspects as: how hard is to maintain the application or how hard is to take on board a new developer.

In my opinion, the main indicators for code quality are: simplicity, readability, robustness and testability. Other qualities as performance or extensibility, if not required, will over engineer your application.

3.- Empowerment.

People are the most valued resource in software development, not the technologies. They are the ones that make the difference between a mediocre product and an excellent product, but they need to be empowered

Empowerment is the process where people is encouraged to be proactive and take decisions. Some of the most effective mechanisms to empower are: coaching, pairing or delegating.

There is an excellent article from Tony Morgan explaining the difference between a classic delegation approach and empowerment.

4.- Continuous integration.

Integration is, from my experience, a major issue in software development. Waiting to integrate at the end of the project or after a big chunk of functionality is completed, is always a traumatic process.

Continuous integration is the process that guarantees that every piece of code committed is automatically integrated in the system. Remember that continuous integration goes beyond continuous compilation.

This article from Martin Fowler, is one of the best references online about continuous integration.

5.- Iterations.

Iterations provide continuous feedback. Continuous feedback is important because it reduces the amount of uncertainty in software development.

While iterations are usually only related to agile methodologies, it is important to remember that there are other methodologies as RUP which also use iterations and they are not part of the agile family.

6.- Automated testing.

Allows refactoring and iterations, provides confidence and if well implemented, enhances the correctness of the final product. To automate tests you may consider some facts about testing and some advices on how to write a good test suite.

7.- Refactoring.

No matter how much care you put on coding, on your first attempt, you are going to be wrong. Refactoring is the practice by which we keep changing the code to meet the changes necessary to introduce in the system.

8.- Informal architecture.

Big design upfront (BDUF), unless you are NASA and can expend 50-60% percent of your project time on it, is a complete waste, but so it is coding without any preparation. Informal architecture is a compromise solution where architecture is discussed in an ongoing basics and is persisted in light documents, boards or similar.

9.- Communication.

Software development is ONLY about communication. The customer explains to the software development team what he wants to accomplish so that the software development team can explain it through code to a computer.

10.- Avoid waste.

Waste accounts is one of the major productivity killers in software development: unnecesary meetings, unnecessary requirements, unnecesary process, unnecesary documentation, being some of the most common and dangerous.

Bug tracking systems are bottlenecks, they perpetuate the continuous handovers between testers and developers and they require extensive documentation to be maintained.

The standard life cycle of a bug is usually as follows: A QA tester finds an error in the application, creates a new bug in their bug tracking system and sends it to the developer, which in turn, as soon as he fixes the bug, notifies back to the QA tester, which then, notifies the product owner which then, closes the bug.

In paper, the previous process sounds wonderful, but there are quite a few drawbacks.

• Communication problems. Sometimes the description of the bug is poor, or the developer misunderstands the problem.
• Regression testing. This process requires the handover of code back and forward between QA and development, this causes versioning problems and duplicated testing effort.
• Low robustness. The process doesn’t guarantee that the error will appear again in the future.
• Bureaucracy.Traditional bug tracking systems switches the team focus to bureaucracy from quality.

The solution for this problems is simple. When anyone finds a bug, he/she immediately writes an automated test that fails based on the bug just discovered. This mechanism have the following advantages.

• Gets rid of versioning problems, everyone works on the head.
• Guarantees that the bug is never gonna reappear undetected.
• Eliminates uncertainty on what the bug exactly is.
• Eliminates bureaucracy
• Consolidates the development activities in one place, the code.

The challenges to switch to this process, where a bug tracking system is not necessary are:

• Requires an automated build. This build have to be in place and running all the automated tests, so when a new automated test is entered because of a bug, the build will break and the team will have to take a decision whether they will fix the fix now, or whether they will ignore it for the time being (That way you will know that all the ignored tests are non-fixed bugs)
• Requires cooperation. Developers and testers must work together so they can create new tests as soon as they find new bugs. You are going to require testers with programming skills.
• Requires discipline. The team must understand that without exception, for every bug found, a test is created, and for every time the build is broken, the priority is to fix the build.
• Requires organization. Tests must be created with criteria and using a common naming convention.

Summarizing, in my opinion, the future of bug management is to get rid of all the traditional bug tracking systems and all the bureaucracy, I also think, as explained just above, that there are quite a few challenges, but if you have the skills and tools in your team to overcome them, I would seriously think about getting rid already of your old bug tracking system.

The research to become a better software developer is core to any good software developer. Being a better software developer reflects directly in the code you produce, the better software developer you are, the less bugs, easier to read and easier to maintain code you will produce.

What follow are the four rules I use on my day to day work to help me become a better software developer.

Rule number 1:  My code is crap.

All code is crap, and that includes yours, (and mine, of course). No matter how brilliant a piece of code you think it is, there will be always better ways to implement it, and several programmers who will hate it.

Even if you are sure your code happens to be good, force yourself into “my code is crap” mode, and ask around about improvements, be open minded and you will see soon how you will find issues in your code that you never have thought about.

Rule number 2: Even if it’s crap, I care about my code.

It is not about creating the best code upfront, is about making it better every time you visit it. When you finish some functionality, you are not done, I haven’t met any programmer that produces acceptable code on their first attempt, you need to polish it. Refactoring is then one of the main activities you should be performing.

Rule number 3: My opinion about my own code is wrong.

We are so egocentric that we end up believing that what we have produced, no matter how bad it is, is the best solution as possible. Never trust your own opinion, show your code to as much developers as possible and listen to them.

Rule number 4: My manager doesn’t care about my code, and he pays me.

This rule regulates the other three, it is easy to forget that you actually get paid to get things done, your manager should also care about the code, but he is more focused in completing things on time with an acceptable quality, so be careful not to expend too much time just making sure your code is not that crap. The key is being able to balance getting things done and their quality.

Bonus: A few tips to help you with these rules.

• Code reviews.
• Keep it simple.
• Test.
• Refactor.
• Non technical factors.

1.- WTF!

The most repeated sentence in code reviews…
Original Source

2.- It works in my machine!

We all have used this one when blamed for some error…

3.- D’oh!

- Hi Homer, have you removed the debug code from production?

4.- It will be ready tomorrow.

The problem with this sentence is that we use it again the next day, and the next day, and the next day…

5.- Have you tried turning it off and on again?

The TV series  ”The It Crowd” have helped to make this one even more popular…

6.- Why?

Why do we keep asking why?

7.- Is not a bug, it’s a feature.

- It restarts twice a day?!! Well that makes sure that the temporary files get deleted!

Original source

8.- That code is crap.

All code is crap except mine.

9.- My code is compiling…

Original source

10.- No, I don’t know how to fix the microwave.

For some reason, non technical people use to think that every thing with buttons can be fixed by a programmer…

One of the most critical moments for a team is when they need to hire a new programmer, choosing the right people is what makes the difference between great teams and poor teams.

Some companies are tempted to have short selection processes because the cost involved is high, but hey forget that the cost of having the wrong guy in the team is much higher.

These are my three tips to help you hire the right programmer for your team

1.- Make the candidate draw a high level design.

This activity will help you to know how good designer the candidate is.

Ask the candidate to explain in a board the architecture and design of some previous application he has developed. This will allow you to engage him in an open conversation, by the end of it you should be able to answer yourself the following questions:

• How good was he explaining the design? One of the most important qualities of a programmer is his communication skills, is almost as important as the quality of the design, if the candidate is not  able to explain it in a clear, concise and focused manner, then how is the rest of the team going to understand it?
• How good was the design?
• How good was he answering your questions? You want to make sure that the design he is explaining is his design, so ask him a few questions and see how he answers you, based on that you should be able to tell if he is really the author of the design.

2.- Make the candidate write some code.

This activity will help you to know if the candidate is able to produce working code in a realistic time frame.

There is a very popular article from Joel Spolsky “12 steps to become a better code” where he states as point 11 “Do new candidates write code during their interview? “, well, I couldn’t agree more, that will give you an unique perspective on how the candidate really performs, there are still a few considerations.

• Leave him alone in a room with a computer, just come back when the time is over.
• Make him code using the same tools he would use in the position he is applying for.
• Leave him enough time to complete the task
  

3.- Make the candidate review some working code.

This activity will help you to see if the candidate has a good sense of what good code is and will help you to determine how good he is reading code.

By asking the candidate to write some code, you should have some idea on how clean his code is, but that could be a false impression as you will be judging based on a piece of code which has been written under quite pressure, that’s where this other activity will help you, hand him over some poor functional code written in the language he is applying for, and leave him alone with it for as much time as you think he will need to review it, then come back and ask him the following questions.

• What is the purpose of the code?
• What do you think of the code, is it a clean code?
• What would you change from the code to convert it into clean code?

There are two sets of skills that a good software developer needs to cultivate: technical skills, and non technical skills. Unfortunately some developers focus only on the technical part. When this happens they will develop some bad habits from which the following are the 5 top non-technical mistakes:

1.- Lack of discipline.

“Discipline is the bridge between goals and accomplishment.” Jim Rohn.

I’ve always thought that discipline is one of the most valuable skills, not only for being a software developer, but to be successful at any other area in life It is also true that usually it is very hard to find people who are both brilliant and disciplined.

Steve Pavlina highlight the 5 pillars of self discipline…  “[...]Acceptance, Willpower, Hard Work, Industry, and Persistence. If you take the first letter of each word, you get the acronym “A WHIP” — a convenient way to remember them, since many people associate self-discipline with whipping themselves into shape.[...]” I highly recommend to read his series of articles in self discipline.

As I explained in my previous article: 5 tips for creating good code every day, my personal approach is to follow these steps every day.

• Have your own to do list for the day
• Do one thing at a time
• Do it right
• Don’t finish something until it’s completely done
• Better late than sorry BUT better sorry than never.

2.- Big egos.

My experience says that big egos and programmers go hand by hand, the main problem of having a big ego is that it actually prevents you from realizing that you have a big ego, a few indicators that may help you to know if your ego is way too big are:

• You consider yourself the best programmer.
• You block conversations.
• You ask for code reviews not to get criticism but to show how good your code is.

There are many good articles about programmers and their ego in the Internet, I would recommend two of them, this article from Mike Bernat: Egoless programmin and from stackoverflow.com this discussion thread.

3.- Being a bad communicator.

“If I am to speak ten minutes, I need a week for preparation; if fifteen minutes, three days; if half an hour, two days; if an hour, I am ready now“. Woodrow Wilson

As human beings communication is our main activity. Being a good communicator is hard but essential in our profession, we are continuously exchanging opinions about designs, code, having peer reviews, writing documentation, trying to convince someone else that our design is better, writing code…

Good communicators are those people that when they are explaining something, their explanation is:

• Focus. They just talk about what is need to be understand.
• Clear. Easy to understand.
• Concise. Nothing to be added, nothing to be taken.

For being a better communicator, I have two advices:

• If you think you are not a good communicator, prepare what you are going to say until is focus, clear and concise.
• If engaged in a conversation, first listen, then think and then talk.

There are a few more tips for improving communication when having a meeting in this previous article I published “7 best practices for taking decisions in the development team“.

4.- Forgetting about the customer.

“If we don’t take care of the customer… somebody else will.”

You are there just for one reason- your customer. It’s easy sometimes to forget this point. I have been in teams where focus was on technologies and platforms rather than in having a happy customer. We would expend months creating a framework that didn’t deliver any value to the customer, and by the time we were about to start using it, we would discover that it won’t fit our user needs.

5.- Not prioritizing the work properly.

Developers who are always gold plating, researching new and more interesting technologies, over engineering solutions or just doing whatever they find more cool are impediments to the project, I’m not saying that is not normal to engage into lateral activities from time to time, we all need distractions, but if you find yourself usually in the previous situations you may reconsider the way you prioritize your work, again I will recommend you to read 5 tips for creating good code every day.

As explained in the article the pyramid of software quality, readability is one of the most important characteristics of good code. These are a few tips that may help you to produce it.

1.- Use a top down approach (TDD).

Using a top down approach is similar to TDD you start with the highest level logic: the validation of what your code has to perform (The unit test), and then you add layers of abstraction, which as you keep coding become more separated from the domain problem and more related with implementation details. This approach helps to produce more readable code because:

1. Producing the unit tests will give you a general idea about how readable is your code. Readable unit tests generally mean readable code.
2. Separating the implementation details and the domain logic makes them easy to understand.

2.- Make your design match your domain (LRG and DDD).

In the excellent book applying UML and patterns, Craig Larman introduces the concept of Low Representational Gap (LRG). The representational gap is how different is the domain logic of an application from its design, having a low representational gap means that the design has very few differences with the domain logic it represents. LRG and Domain Driven Design DDD are much related concepts as they both focus on designing a domain model that matches the real model.

An application that has a LRG will be much easier to read because the actual domain logic will match the implementation domain logic.

3.- Use abstractions only when necessary (YAGNI and KISS).

Sometimes is tempting to make everything too much flexible. As software developers we always have to have in mind these two principles: You Are Not Going to Need It (YAGNI) and Keep It Short and Simple (KISS), remember: Code is not better because it has abstraction layers that may be useful in the future, they are going to make your code harder to read, just use abstraction layers when you need them now, not just in case they are necessary in the future.

4.- Use good names.

Using good names in your code is critical, it will make a difference between a code which will be read as plain English and a code where you will be shouting WTF?!! every two lines.

In this article: tips to write variable names, there are a few tips that can actually be applied to name any named element not only variables.

5.- The 5 minutes explanation test.

Apart from using the previous 4 tips and some other guidelines you may think appropriate to create readable code, I like to pass the 5 minutes explanation test to my code to know how readable it is.

1. Grab a fellow programmer who spares some time to review your code
2. Walk him through your code, just a high level introduction.
3. Ask him if he understood your code.

After following these steps you can evaluate how readable your code is based on how much it took you to explain it. I call it the 5 minutes explanation test because as a rule of thumb if it takes more than 5 minutes for the other programmer to have a high level idea of the design, assume that the code is not readable.

1.- DRY: Don’t repeat yourself.

DRY is usually the easiest principle to understand, but it is quite harder to apply. It means that when finding similar code in two or more places, we should abstract them into a new method and change the previous code fragments so they will now call the new method with the appropriate parameters.

DRY is maybe the most universal coding principle, I have never found a developer who would argue that repeating code is good, but, I have found developers that forget about this principle when coding unit tests, as an example: imagine that you have changed the interface of a class which had lots of unit tests, if you haven’t used DRY, you will have to manually change the call to this class interface to match the new signatures to each test case.

2.- Write short methods.

There are three very good reasons for writing short methods.

1. Your code will be easier to read.
2. Your code will be easier to reuse (short methods are likely to produce loose coupling).
3. Your code will be easier to test.

3.- Use good names for your classes, methods and variables.

There is nothing nicer than using some other developer code and not having to read its documentation because the names of the classes and the methods are telling us everything, so, make everyone’s life easier and take this approach, expend always a few seconds before naming any element in your code.

4.- Assign the right responsibility to each class.

One class, one responsibility, that will sound familiar to those who know about the SOLID principles, but not any responsibility, the right responsibility, so if we have the class Customer, we won’t assign to it the responsibility to create a new sales action, we will just assign it the responsibility to handle all the data related with a customer.

5.- Keep your code organized.

This organization is at two levels.

• Physical organization: Whatever the structure you are using, packages, namespaces, folders… Organize your classes in such a way that is easy and intuitive to find where the code is stored.
• Logical organization: Whatever belongs logically together should have access to each other members, but what belongs to a different logic structure has to access them by an interface. These logic groups are commonly implemented as layers, services…

6.- Create lots of unit tests.

The most tests you have, the better, they are our safety net for all the changes we will have to perform in the code in the future.

7.- Refactor often and sooner.

Software development is a continuous discovery process, in order to keep up to date with good code that matches the new/changing requirements is essential to refactor the code as we go. As this is a risky task there are 2 main preconditions to avoid entering new bugs into the system.

1. Have lots of unit tests.
2. Do small refactor steps at a time. In software development there are very few things more annoying than start refactoring 2000 lines of code to after 3 hours of work realize that is necessary to roll back to the original version because now nothing works and the track of which change is causing the problem is lost.

8.- Comments are evil.

This particular one is a bit controversial, most of us were taught that comments are good, and actually it’s better to have a comment in an obscure piece of code than just having the code by itself, what this point means is that: even better than having a comment for an obscure piece of code is to not to have that code at all, just refactor it until is a nice and readable piece of code. [EDIT] Please read this other post for a better explanation of what “comments are evil” means.

9.- Code to an interface, not to an implementation.

This is a classic one, coding to an interface will free us from the implementation details, we just define a contract and rely on calling the defined operations on the contract, expecting that the actual implementation will be passed to our code or decided at runtime.

10.- Have code reviews.

We all make mistakes, and there’s nothing better than asking some other person to have a quick and informal review in our code to find them, in order to make the reviews,  it’s better not to wait until the code is completed, it’s better to ask for reviews whenever some important part of the code has been completed or when a few days have passed from the previous review.

There are many articles on Internet with tips on how to become a better developer,  most of them focus on promoting learning attitudes like reading articles, books…

• Ryan Farley – Becoming a Better Developer
• Bil Simser – Being a Better Developer… in 6 months
• Justice Gray – How I am becoming a better developer, part 1 of infinity
• Rodrigo Diaz – How to be a better developer?

In this article I want to approach this subject from a different perspective I am going to present a few unusual tips which I believe will help you to become a better developer.

Be adaptable to any work environment (there is no “I” in team)

You may be a convinced agile practitioner or a waterfall one, but in the team where you are working they are not. Or you may be in a design session where you don’t agree with what has been decided…

You will always face conflicts, a good developer will know when it’s time for discussion and when it’s time to stick with the team and do as best as possible. The worst dynamic for a team, it’s when the people are not aligned in the same direction. (article from Jeff Atwood – codinghorror.com about this issue) .

This means that when a decision has been made you shouldn’t use every opportunity, every meeting, to remind your colleagues how wrong you think they are, you will be just mining the team confidence. One of the worst aspects I have observed from software developers is their ego, I’ve seen many times how attitudes like “If it’s not my way, no way” gets in the middle of getting things done.

This doesn’t mean that you don’t have to fight for your opinions and ideas, there is a time to make decisions and that’s when you have to bring all your ideas, after a decision is made, embrace it as if it was your decision, if you can’t is better that you just talk with your manager and you leave that team.

This doesn’t mean either that you have to give up if you see that the team goes in the wrong direction just because a decision has been already made, wait to have evidence that the team’s direction is not the right one, think on how to improve it and show it to your colleagues with a positive attitude

Understand that most of the times everyone is wrong

Drop the attitude “I’m right, You’re not”, both of you are wrong. In the software development industry I’ve seen very few times situations where someone holds all the truth about something, is very likely that in a software discussion all the parts involved are just partially right, a good software developer has to be able to recognize what can be bundle from everyone’s opinions in order to come up with the best possible solution.

Don’t get stressed. Enjoy what you are doing.

I keep reading articles about telling developers to read blogs, books, to code in your spare time, to write your own posts… And it’s not that I don’t think that it won’t help you to be a better software developer, of course it will, but it can also be really bad for you.

I actually wrote an article about how passion is the main difference between a good software developer and an average software developer, but if that passion is pushing you to the point where you are getting stressed, just take one step back.

• If you are not enjoying it, why are you doing it?
• If you are not enjoying it, you will eventually quit.