Making Good Software

A blog by Alberto G (Alberto Gutierrez)

Archive for the ‘Popular’ Category

Top 7 programmers bad habits

with 21 comments

1.- The all code is crap, except mine, attitude.

I have bad news for you buddy, all code is crap. No matter how much effort you put on it, there is always a majority of programmers who are going to think that your code sucks and that they could have done it 10 times better. I have already covered this topic in previous posts, you can find more information of what exactly I mean when I say that all the code is crap here and here.

How to fix it: Don’t criticise others people code, it could be yours the one in the spotlight, try to make objective and professional observations instead, but don’t judge. Be humble and try to learn from everyone around you, hopefully then your code won’t be so bad.

2.- The “I fix that in a second” catastrophe.

homer-simpson-dohTaking shortcuts is very tempting, everyone has done it. There are actually situations where they are necessary, but in overall, they are dangerous, very dangerous and should be avoided. A shortcut which goes wrong may save you a few hours, but may cause months of pain.

How to fix it: Don’t trust yourself when carrying delicate activities. Ask someone else to review what you are doing. Make sure that if you are about to take a shortcut, you make very clear to the stakeholders what the reasons and the risks are. Try to get a manager to sign off every time you are about to take a shortcut, aka “cover your ass”.

3.- The “That will only take a second” misconception.

Being Barcelona my hometown, I am very proud of the Sagrada Familia Cathedral, which is very well know for its beautiness, and also for the time is estimated it will take to complete, (in construction since 1882), but that’s probably because they didn’t ask a programmer to estimate, otherwise the estimate would probably have been somewhere around 2 weeks.

How to fix it: For starters, is important to understand that accurate estimations in software development for non trivial solutions are impossible, we can only guess. Also remember that is very likely that you will find so many things which you didn’t foresee when you start developing that is worth multiplying the estimate to cover for those, I usually go with 1.5 or 2.

4.- The ego spiral.

chicken dance

The last design meeting...

Many programmers discussions look more like rooster fights than human discussions. This usually happens in design and architectural meetings. It is actually quite easy to detect this ego spirals, you just have to substitute most of what the contenders are saying with COC! COC! COCOCOOCCC! COOC!

How to fix it: Leave your ego at home. Big egos are one of the biggest non technical issues for any programmer. Keep in mind some basic considerations when making decisions.

5.- “It wasn’t me!”

In my opinion, other bad habit from most programmers is the lack of accountability. We always have an excuse… It’s like if we were saying that under normal conditions we would never make a mistake, which honestly is quite hard to believe.

How to fix it: No need to cry, or to perform seppuku, (aka harakiri), when we make a mistake. Having a healthy attitude where we can you just say something like: “yeah, sorry, now we need to do this to fix this issue, my fault” is a very professional attitude, and it will help you to build a reputation and to be better considered by your colleagues.

6.- The demotivated genius.

Repetitive and simple tasks are not the best motivators, but they need to be done, programmers tend to get demotivated and very unproductive when they need to complete them.

How to fix it: Discipline. Unfortunately, there isn’t any other remedy I can think of.

7.- The premature programmer.

If programming was sex, there would be a lot of unsatisfied computers. You can just not go in, do things halfway through and then fall sleep. One of the concepts that I find most programmers struggling with is the concept of “Done”. Remember that done means: tested (and not only unit tested), documented, committed, merged…

How to fix it: This one is tricky, the complexity of non apparent necessary tasks to fully complete some functionality is quite high and usually requires discipline and training. Probably the two easiest ways to help a programmer understand if some code is done are peer reviews and demos.

Written by Alberto Gutierrez

May 23rd, 2011 at 3:36 pm

The obsession with beautiful code, the refactor syndrome.

with 18 comments

There is lately an emerging obsession with beatiful code, up to the point where some programmers are overprioritizing it over more important goals such as:

  • Correctness
  • Robustness
  • Traceability
  • Supportability

When this is taken to the extreme, and all that the programmer cares about is the beauty of the code, can cause him/her to fall under the refactor syndrome.

The refactor syndrome has the following symptoms:

And usually causes:

  • An explosion of services, managers, helpers or other utility like classes.
  • Integration bugs.
  • Lack of robustness.
  • Loss of productivity.

The main issue with the refactoring syndrome is that is based in the beauty of the code, and this, upfront, has three big issues.

  1. Not achievable. All code is crap. This is one of my favorite quotes, and to me is proven by the following facts:
    • Exclusion principle. All programmers tend to think that only their code is the only good code in the universe.
    • Legacy code principle. As a programmer, as you learn new stuff, you even consider your not so new code to be crap.
    • Experience principle.I have never seen, or produced any real code which I thought it was beautiful.
  2. Not so important. Even if beatiful code was achievable, it doesn’t prove that the code is correct, and among other things, correctness is way more important than beauty.
  3. Wrong perspective. Focusing in the code itself, and not in the application makes the programmer forget about other more important areas.

This refactor syndrome seems to be associated with some programmers taking the last agile tendencies as religious dogmas. This happens when programmers confuse the tools and engineering practies like TDD, refactoring, pairing and unit testing… with what needs to be achieved. This would be comparable to a builder who believes that having shiny, new and clean tools, is more important than the house he is building.

It is important to understand that none of the tools or engineering process that the different agile family of processes propose are bad per se, they are usually great. Is just that when we decide to overuse them that we might be getting close to the refactoring syndrome.

In summary, is important to remember that:

  1. It is not important how beatiful is your code if it doesn’t work.
  2. Refactor only when is necessary, not only when you don’t like the code or you think you are going to make it more beatiful. Not liking something IS NOT a reason enough to change it.
  3. Unit tests have very limited value when it comes to integration and end to end issues. Do real end to end test!!
  4. Know all the different tools and engineering practices, but don’t take them as dogmas, learn what is good and bad from each and apply them when necessary.
  5. Good programmers are gonna keep doing good software, bad programmers are gonna keep doing bad software, no matter what processes they follow.

Update

Apparently this article is causing some controversy, so I want to make clear some points which I see after the comments I didn’t made clear enough.

  1. I do think that Unit Test is great, I just want to point out that it CAN’T and it SHOULDN’T pretend to substitute integration and end to end test from the developer.
  2. When I say that a bad programmer is going to write bad software, no matter what process he follows, I didn’t mean to say as in, a bad programmer also will always be a bad programmer, we all have been very bad programmers when we started, and we only hope that we improve as we aquire more experience.

Written by Alberto Gutierrez

March 27th, 2011 at 12:19 pm

Agile dogmas: You shall never do any design.

with 9 comments

Agile has become one of the most beneficial and needed change in software development. It has helped to move the focus of software development:

  • From: Project managers, architects, documentation and requirements.
  • To: Programmers, implementation and opened discussions.

Paradoxically, some companies and programmers are pushing this change of paradigm so hard, that they are falling in the very same errors that doomed waterfall: Lack of flexibility and dogmatism.

One of the most popular dogmas among the agile community is: “you shall never do any design.”. This dogma it’s been mostly influenced by TDD, and that’s why this article focuses on it

TDD and its core pattern “red-green-refactor”, is an emergent design engineering practice that can dramatically improve the quality of the code. Being based in emergent design means that is not necessary to do any explicit design in software development, but that the design will flourish from the implementation.

The issue with TDD, as with any other emergent design approach, is that it doesn’t make any differentiation between the implementation design level (tactics), and the architectural design level (strategy). This lack of differentiation between strategy and tactics, for simple developments is OK, but for more complex developments becomes an issue.

A good metaphor would be climbing a mountain. Let’s imagine two different approaches; one where every single step of the route is prepared beforehand, and the other where we would just start climbing paying attention just to what we have a few steps ahead of us. The first approach would be the equivalent of an extremist waterfall approach; the second would be the equivalent of an extremist approach to agile. Obviously none of them would work.

Software development is, in that sense, like climbing a mountain. It is necessary to have a strategy and a tactic. Is also important to realize that, as climbing, we have to adapt to the different circumstances we face in the day to day of software development.

TDD, as any other emergent design technique, is ideal for the tactical part of software development, but they ignore the strategic part, which for complex developments is very important.

One of the biggest factors to determine whether a development is simple or complex is uncertainty. Having a high uncertainty means that there are a lot of critical details from the development that are no evident. When uncertainty is high, is when we can take advantage of doing design.

One sample of simple development, with almost no uncertainty, and which won’t require any previous design would be developing a component that would take a quantity and a percentage and would tell us what the interests are at the end of the year.

An example of a more complex development would be to develop a component that would be able to resolve a Sudoku. In this case we would take advantage of doing some previous design.

When doing designs, is important to take into consideration the following guidelines:

  1. The design should be informal. It shouldn’t have to be in any particular format or using any particular methodology.
  2. The design should be incomplete. We should distance from the Waterfall BDUF, we only want to capture the 20% of the essence, which is going to help us fix the 80% of our problems.
  3. The design should be small, and should take short time. We shouldn’t expend more than 2 hours doing the design, if so, the reason would probably be that we need to split the development into smaller development items.
  4. The design should be democratic and simple. This means that there shouldn’t be any architect throwing the design to the programmers. The design should be done via open discussions with your colleagues, and simplicity should be preferred to any other approach.
  5. The design changes and evolves. We have to move away from the waterfall approach where the design is static, in agile, the design should be used to help us identify the bigger picture and it changes as we discover hidden aspects of what we are developing.

Continuing with the previous Sudoku example and with the design guidelines just commented above, one design approach for a component that resolves Sudokus summarized in a few points, could be:

  • To find the solution for a Sudoku we have to guess, one at a time, what are the missing numbers in the empty cells.
  • The best approach to pick the next number to guess is to find a blank spot in the Sudoku that can only hold 1 valid number.
  • When a solution for one cell is found, a new Sudoku with that cell filled is created and recursively we keep looking for the next solution until all the cells are filled. Then the Sudoku is solved.
  • When there isn’t any cell with an unique possible value, we have to search the cell with the less amount of valid possible values and create an hypothesis from there. That’s it, from the list of possible values, pick randomly one of them.
  • With the hypothesis we keep looking for the solution as if it wasn’t an hypothesis, but a completely valid solution. The difference is that with hypothesis, if we ever get to a point where there isn’t any possible solution, we go back to the originating Sudoku of the current hypothesis, and we create a new hypothesis.
  • The hypothesis can contain other hypothesis.

It is important to realize from the previous design that it doesn’t get into implementation details, and is very informal. They are only a few guidelines to help with the development.

Even thought, they may not seen very important, this mini design sessions are key to help developers to obtain the bigger picture of what they are developing. Remember:

  • It is not right to try to guess beforehand what are all the directions we have to take paying no attention to the road.
  • Neither it is, to start walking only to realize 2 kilometres later that we took the wrong direction.

Balancing out the right amount and timing of designing and coding is, with any question, a quality common to all the best programmers in the world.

Written by Alberto Gutierrez

December 21st, 2010 at 1:37 pm

Demystifying agile, top 7 myths.

with 9 comments

After a few years of experience working with agile, I have come to the conclusion that many of its principles are just buzz talking targeted to management and that they don’t help in the development of the application.

What follows is a list of the most common myths I have seen around agile. Please, feel free to add a HA! After you mentally read each of their titles.

1.- Stories are better if you follow such and such conventions to create them.

Have you ever had a fight over the best convention to use to name a story? Or have you ever expend hours trying to split your backlog into stories that fit such and such criteria? Or maybe spend weeks deciding the best application to store them?

There is a funny fact about stories, when there is a communication issue in the team, stories are usually blamed: They are not clear enough, the acceptance criteria wasn’t good enough, the color of the cards was wrong…

Stories are great placeholders for discussions between development, management, QA and the customer. That’s all they are. All you need to do is make sure that everybody involved understands them and keeps an open discussion.

The ones to blame when communication doesn’t work is the team, and the solution is usually not improving the stories, but improving the communication.

2.- Planning, with agile is fun and accurate.

Fact: Planning in software development is not accurate. You can use days, hours, points, play poker or blackjak, is not going to work, and if it works is usually by coincidence. So, should we stop planning? … mmm… I don’t think managers would be very happy about that.

Definitely planning adds value, it tells you about the scope of the task: is it hours/days/weeks? And it helps to determine the percentage of completion of functionality of the application. It is also useful to set expectations for management.

Agile actually does a good job setting the right expectations. With agile the customer should legitimately expect to receive the best solution as possible for a given date, but agile is not going to tell you when you are going to be finished, still is probably going to be more accurate than waterfall.

3.- Daily stand-up, the communication panacea.

Stand-ups don’t substitute communication in the team, but some agile teams tend to think so, the “let’s raise it in the tomorrow’s stand-up” approach, doesn’t work.

Stand-ups are ok, they provide an overview for the previous and the current day, but that’s all they are. Communication is very important in software development and it can’t be limited to a 10 minutes discussion in the morning.

4.- Agile the process that fits everything.

Agile is not the silver bullet. That’s probably one of the most repeated sentences in agile environments; still, I have seen the very same people that say so behave like if it was.

Applying agile principles to everything is not only wrong, but lends to dogmatic ridiculous situations, like never documenting the code, never creating documentation or never creating even a light design upfront.

Software development is a complex matter that requires different approaches depending the circumstances, sometimes a waterfall approach is better suit than an agile approach or vice versa, and most of the times what is going to be better suit is going to be a mixed approach.

5.- Retrospectives, they fix everything.

Not only is a bad practice to wait for the retrospective to raise an issue, is childish to expect them to be fixed just because they get raised, issues raised in retrospectives are usually serious impediments, and management tend to leave them for after, which usually means never.

Over the years I have come to the conclusion that removing impediments or improving the process are usually up to individuals. “Hero developers” make most of the big differences made in software development.

These hero developers are the ones that usually get fed up of not having SCM or not having an automated test suite… And they decide to champion an action and fix things on their own terms.

6- Unit tests is all you need.

There is a tendency in agile to believe that unit tests is all you need. But the problem is that the major issues are always in the integration points and E2E aspects of the application, and that’s something that your unit test are never going to highlight. Unit tests are still very important, they have a lot of value for refactoring and to help you design your code, but keep in mind that you are still going to require integration, end to end, adhoc and other types of testing to guarantee the quality of your product.

Another stupid affirmation is the ones that refer to an specific necessary quantity of code coverage in the project. This type of metrics are useless and usually come from people that has never coded for real. Your unit tests must cover parts of your application that contains your business logics, not getters, setters, integration points etc.

7.- Agile is a process fitted for junior programmers.

Short answer: No, agile is not a process suited for junior programmers. Agile switches the main responsibilities of the development from a few to everyone in the team.

Everyone is responsible for maintaining the quality of the application, and when you asked someone without experience for this kind of responsibility you are calling for troubles.

Written by Alberto Gutierrez

November 7th, 2010 at 2:44 pm

10+1 things they never teach in college about programming.

with 58 comments

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!

Written by Alberto Gutierrez

May 27th, 2010 at 4:29 am

Posted in Popular

My ten development principles

with 20 comments

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.

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.

requirements-communication

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.

Written by Alberto Gutierrez

March 13th, 2010 at 1:36 pm

The four golden rules to be a better software developer.

with 15 comments

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.

Written by Alberto Gutierrez

November 9th, 2009 at 5:42 am

Programmers top 10 sentences

with 75 comments

1.- WTF!

The most repeated sentence in code reviews…
wtfmOriginal 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?

homer-simpson-doh

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!

bug_vs_featureOriginal source

8.- That code is crap.

All code is crap except mine.

9.- My code is compiling…

xkcdCompiling

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…

Written by Alberto Gutierrez

September 1st, 2009 at 4:54 pm

5 top non-technical mistakes made by programmers

with 49 comments

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.
homer-simpson-doh

  • 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.

Written by Alberto Gutierrez

July 7th, 2009 at 9:43 am

How to write readable code? 5 Tips to improve your code readability.

with 2 comments

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.

Written by Alberto Gutierrez

June 22nd, 2009 at 5:45 pm