Testing Is Important, So Plan It Soon

First of all, I want to apologize to all my readers for being away for so long. Personal reasons have kept me away from posting but things are settling down, so I want to resume this enjoyable task, and I hope you keep following my work.

I left my work a few months ago trying to define all the strategies every software development project should define before any work is done. I described many of them, which you will find in earlier posts. Today, I will talk about testing.

I have never talk to anyone in the software development industry who did not believe that testing was one of the most important task in any project. You can ask anyone, and they will tell you that if you want to develop high quality software, you need to test your product. Even so, different people have different opinions on how to test software, and to be honest, they all have a point. This is why you need a testing strategy. You need to make very clear how the software you are developing is going to be tested, and whose responsibility is to test the different parts of your application.

Automation Is Your Friend

Testing is not fun. Manual testing is even worst, and it takes a long time and many resources. Invest in automation, so you can test quicker and more often. There are many tools out there that can help you automate your tests. Learn them and use them. In the long run, it will be worth it.

You Need Manual Tests

There is no way you can automate every single scenario. The reason is very simple. It is impossible that you will think of every possible scenario in advance to implement an automated test. However, when people are manually testing a program, they will come up with very clever ways to break it. Manual testing is important to allow people to be creative about testing.

Once you have found a scenario you did not think about before, you should document it and automate it to make sure you can test it over and over again.

Testing Starts During Development

Testing is a responsibility that begins in the development team. The higher percentage of defects in software can be found by testing during development.

Automated unit tests can help you to test often and insure the code is exercised at the lower level, where most of the defects are initially introduced. They will also help to validate the defects are fixed after they are found.

Testing Continues After You Ship

Some people think that once the product is out the door testing is complete. Unfortunately, there will be defects you have not found because of scenarios you have not think about. You should keep testing after you ship your product. Maybe, you will find defects that can be fixed in a service pack.

Furthermore, your customers will find defects you have not seen before or think about. Treat these defects with the same importance as if they were reported by your QA team. Even give them a higher importance. The defects your customers are reporting are really annoying them and giving your software a perception of poor quality.

The longer it takes to find a defect, the more expensive and difficult it is to fix it. The only way you can find defects is by testing, so the sooner you start testing, the sooner you will start finding the defects and fixing them. The sooner you define a testing strategy, the sooner you can start testing. Your testing strategy is key to the success of you software development project, so start planning before any development is performed.

Coding Standards: The Real Importance

A lot of times people think of coding standards as the place where you put the brackets in a code block. Aesthetical standards are nice to have to give consistency to the code. But, the real importance of coding standard is about establishing a mechanism to detect common mistakes and possible errors that can happen while writing code.

Not a believer on coding standards my self, I got my eyes opened when I read the book C++ Coding Standards: 101 Rules, Guidelines, and Best Practices by Sutter and Alexandrescu. As the title suggests, coding standards are not only about naming conventions, indentation, or brackets, but about rules, guidelines, and best practices that you should follow while writing code.

It is nice to define how methods of a class should be named, where you place the brackets after an 'if' statement, or the number of spaces you should use to indent code. This type of things give a consistency to the code that once you get use to them, they make easier to read code written by others. Actually, I have a very strong opinion about how all these things should be done, as I am sure any developer does. But enforcing this type of silly rules, it is not going to help you to achieve your ultimate goal of writing robust quality software. Furthermore, they might have an adverse effect because enforcing these rules can set your team against any type of standard and not follow more important rules.

The rules, guidelines, and best practices defined by your coding standard should focus on common language pitfalls, and the measures to prevent them. More experienced programmers in your team should identify these pitfalls and define the best way to avoid them. Newcomers and less experienced members of the team will benefit from all this documented knowledge, and the quality of your program will increase.

Code reviews should focus, not only on the correct implementation of the feature being reviewed, but also in the correct use of your coding standard. Reviewers must enforce every submission follows the rules, guidelines, and best practices, and when a decision being made violates your coding standard, the decision should be properly documented in the code.

There might be some aesthetical rules or guidelines in your coding standard. Things like separating public, protected, and private members into distinctive blocks can be helpful to understand the implementation of a class, and you should define them in your coding standard if you wish. The capitalization of members or whether you should use a distinctive prefix for data members of the class can help readability and should be part of your standard. Getting too wrapped-up on things like bracket placement, spaces after parenthesis, or size of indentation can be counterproductive.

You should identify which aesthetical guidelines are actually going to improve the readability of your code. You should concentrate on which guidelines will help to increase the quality of your code because they will make it easier to understand, and which ones will not really matter. You should pick-up your battles because programmers are very opinionated about this type of things, and you do not want any obstacles that will prevent the adoption of your coding standards.

For a long time, I was not a believer in coding standards until Sutter and Alexandrescu open my mind. At the time, C++ was my main programming language, and their book help me a lot back then. Now, I am using other languages, and I wish there was a similar book written for them. I recommend you read the book, even if you are not a C++ programmer because some of the rules will still apply to any modern language (or at least to languages like Java and C#). Some others will not apply, but the book will show you what a good coding standard looks like.

Find the glitches of your programming language, search for the most common pitfalls and mistakes people make when writing code in your language of choice and document the correct way to avoid them. That is a good start for your coding standard. But most important, make sure your team follows what your coding standard defines.

 

Technorati Tags: Programming,Software Development,Coding Standards,Best Practices,Rules,Guidelines

What Should Be Part Of Your Automated Build

Personal reasons have kept me away from this blog for a very long time. It has been longer than I expected, but it seems that finally things are settling down, and I would like to resume this fine and fun practice. And what better way to do it than to resume from where I left.

I started this blog writing about a series of strategies you must define in any software development project. I wrote about the importance of a source code management strategy, and the reasons why you should define a documentation strategy. Now, it is time to talk about your automated build process.

Let me start by saying, if you do not have an automated build process you are doomed to fail. The reasons are simple. Automation will help you to reproduce every necessary step to build your product as many times as you need removing human factors that most likely lead you to failure. People tend to make mistakes; scripts do not. When an automated build process fails is indicative of some human error not a script making a mistake (assuming your script works). Therefore, you want to have a complete automated build process.

An automated build process means different things to different people. In my mind, it only has one definition: the set of automated steps that grab everything needed for your application from you source repository, and operates in it to compile, test, and package your application. Yes, you read it all right; compile, test and package your application.

An ideal build process downloads all the required files from your source repository, compiles and links the source code to create your binaries, runs all your automated tests, and packages your application files into your deployment package. One single click, one single scheduled task launches your build process and spits a package that you can release to your customers at the end of it. So let us talk about what your build process needs to do.

Your Source Repository Is The Beginning Of It All

Every project file should be in your source repository. This includes your source code, documentation source, application data and content, and build scripts. The only file that is not part of your repository is the one and only script that triggers everything, and this script should only download the source and invoke your build process.

Many people see the build process as a separate entity from the product. This is a big mistake. Your build process is going to change in the same way your project changes. New dependencies are added, new files are added to the application, new application content is added to your project. The same way all those files reflects a particular state of the application, your build scripts reflect a particular state that allows you to build your project at a specific point in time. Keeping the project files and the build process separate will only add a maintenance burden to your process, so it is always better to keep them together.

Obviously, It Build Your Binaries

Needless to say, your build process is going to produce the binaries that your application needs. But the process of building the binaries needs to do more than just that.

Binaries will need to be versioned in a consistent way with each new build. Company information might need to be embedded into the binaries, and the binaries might need to be signed. Your documentation and help files might also need to be compiled.

Make sure you build every configuration of the files you need to ship or that are used internally and for every platform you support. This means you should build your release configurations, as well as your debug configurations.

This is what most people understand as the build process. To me, this is just the first step of a bullet-proof build process.

Run Test Automation

Once you have all the files you need for your application, it is wise to test them. If you have automated tests, and you should, run them against your newly created binaries. Make this test run part of your build process to insure your application is tested to some extent with every build.

This does not mean you should not rely on the manual testing your QA department does. As a matter of fact, you are insuring your application runs and can be tested by QA. You will eliminate problems where your application seems to compile but crashes on start-up. Including your automated acceptance tests into your build process will alleviate the headaches QA gets when the build is broken.

Package Your Application

Your automated build process should generate the images for all your deployment packages. Ideally, it will also cut the CD or DVD you intent to ship, but most of the time, and ISO will do.

If you are at the end stages of your project when you are building your release candidates, you can use the packages you produced to ship your product once QA has given the OK.

Many people does not include the ISO generation as part of the build process, and they manually create it afterwards. Guess what, they make mistakes, and they have to recreate the ISO's more than once. Not a good idea when you are in a hurry to ship.

Make Sure You Can Execute All Previous Steps Independently

It is a good idea to isolate each of the previous steps and design them so that they can run by themselves. This will give you a lot of flexibility, and there will be times when you will need this.

You want the ability to just run the compilation steps to create a check build that runs with every check-in against the source repository. This will validate the state of your source with every changes and will allow you to catch errors quicker.

There will be times, especially close to release, where you will only want to re-master your application to include an updated license agreement, help file, or content file. You can achieve this if the application packaging is design in a way that does not depend on the compilation or testing of your application.

You may want to test your application every few hours to insure that changes have not affected stability. In this case, you will want to get the latest source, compile it, and run your automated tests.

Of course, once or twice a day, you want to run through the entire process to validate your production build. This does not mean you are going to release it or give it to QA, but you want to make sure your whole process works.

Notify Your People

It is inevitable. Your build process is going to break. Someone is going to check-in code that does not compile, files are going to be changed or deleted, dependencies are going to change. When this happens, you want to notify immediately to the right people.

A broken build process should be the first priority of your team, and no further development should be done (or at least checked-in into your source repository) until is fixed.

An automated build process is the best way to insure your application is stable at al times. It is the quickest way to get feedback about the changes that are going on in your project. And, you need to build your application to be able to release it. If you rely on manual steps to build your application, things will fail when you least want them to fail. Automation will help you to reproduce the same steps over and over again, and insure that you end up with a working product at the end of each cycle.

Technorati Tags: Software Development,Build Process,Agile Development,Programming

5 Reasons To Have A Documentation Strategy

Documentation is one of those tasks where is very hard to calculate the ROI (return on investment). How can you know how much money you are saving by having good documentation if you do not have an un-documented version of the same project. In the same way, how are you going to compare the time you are saving by not documenting your projects if you have not documented your project and see how long it took.

No, I am not proposing you implement your projects twice, once documented and once undocumented to be able to compare. But the truth is, we do not think too much about documentation until we need it, and by then, it is way too late. So just in case we need it, let's implement a documentation strategy.

First and foremost let me explain that I am not talking about the help files you should write for your application users. This task is better left in the hands of professionals; your tech-pubs department. Your documentation strategy is for the code that goes into your application. This is a more technical documentation, and should be written by the same experts that write the code.

I haven't convinced you yet? Well, let me give you the reasons why you should have a strategy to document your code, and let's see what happens.

1. Complexity Is Best Explained In Plain Language

Despite all the post and articles you read before about how good code is self documenting, how good programmers are able to read and understand code like if it was their first language, and how a clear use of patterns will help you to understand the design and architecture of your application. The truth is that, with the exception of a very small elite group of programmers to which I do not belong, most programmers understand plain language better than any code.

Can a programmer with the right experience go through hundreds or thousands of lines of code and understand what they are doing? Sure he can. But, it is going to take him a lot longer than if he had a few UML class diagrams and some HTML help files describing the API's and their use.

"Wait a minute. Are you proposing to use UML?" Not really, but there are things that are better expressed in a diagram than in plain words (you know, a picture is worth a thousand words).

2. There Are Things Code Cannot Express

Customization points for classes; assumptions being made; side effects. These are all examples of things that cannot be expressed just with code. There are many more, and they will play a very important role once your code moves to maintenance mode.

You might be thinking, "that is what comments are for." Maybe, comments are your documentation strategy. If so, you should define it and make sure everyone understands it, so comments are actually added to the code.

Documentation and code can get out of synch if they are not maintained. Your team must understand the importance of having up-to-date documentation and make sure pertinent changes are made to it when the code changes.

3. Documentation As Training Material

Once in a while, you are forced to hire a less experienced developer, and you will be glad you have good documentation to get him up-to-speed. As he glances through the documentation, he might learn a few tricks that will allow him to become a better programmer. He can still learn a lot looking at code, but documentation is a supplement that can make his life and yours, easier.

New developers usually need some kind of Mentor that guides them through the learning process. You can save many mentoring hours if you have good documentation, and everyone will be more productive.

4. Finding What You Are Looking For

How many times have you implemented some functionality just to discover a few days later that someone had already written the same thing years ago? Undocumented code silently leads to duplication because in medium and big size teams, it is impossible that everyone knows about every single line of code written by other members.

There are many tools out there that will generate automatic documentation in a way that is easy to search and find exactly what you are looking for. This is a big time saver and promotes code reusability.

5. Because We All Forget And We Should Forget

No matter how many items you can keep in your memory (and I am not talking about RAM), sooner or later you will forget how a particular feature you wrote works. It is inevitable. If you did a good job writing the code, things will come back as you look at it, but most of the time, you will be glad you documented it.

There are times when you really want to forget. We all have code we wrote in the past that we do not want to remember. If you don't, most likely it means you have not learned much lately. In my experience, a developer presented with the exact same set of requirements at two different points in time will come out with two completely different solutions. Developers evolve and learn new things that makes them improve. This will drive them to solve the same problem in different ways.

Remember the assumptions I talked about in point two? These will also affect the outcome of the solution. Because we know now what we did not know then, we probably make different assumptions, and many times this will prevent us from understanding what we did in the past unless we have something to refresh our minds: documentation.

Conclusion

Documenting code is not fun. Maintaining documentation is a nightmare. You should plan your documentation strategy before starting a new project, so you can write the documentation from the beginning.

Your documentation strategy should be part of your code writing process. Merging both things together will make it less painful. Select a strategy that is accessible from the source code, find the right tools for you, and make sure everyone understand the importance of this task.

Documentation can bring new members up-to-speed; it can help you to refresh your mind when you need it; and it will prevent you from making the same mistakes over and over. It removes code duplication by exposing existing functionality to your development team, and it will help you to express the concepts that are hard to find and understand by just simply looking at the source code.

6 Areas To Think About Source Code Management

It has been a while since my last post. I took some vacation from work to be able to spend time with my family during the holidays, and they have taken all my time. Now, I am back to work and back to post, and I will continue where I left.

I finished the year talking about seven strategies we should define before starting a software development project. In this and subsequent posts, I will give you the reasons why you should plan ahead and implement those strategies. I will not talk about specific processes or tools. You should evaluate what fits your current situation, but I will point out the things you should think about and what the relevance is for each of the strategies.

Since the first strategy I mentioned was Source Control Management, I will begin the series explaining the areas you should think about when you implement a Source Control Management strategy. I know, you are already using a Source Control Management System (SCM), but an SCM is a tool, and we are not talking about tools. Do you have a strategy on how to use your SCM? Does everyone in your team understand and agrees with your strategy? Your answer might be yes, but keep reading, you might find a couple of things you have not think about.

1. Managing Source Code Changes

If there is something you can be sure about any project is there are going to be changes. In software development, changes in a project usually translate to source code changes. Your Source Code Management strategy should establish how changes are made, and who is allowed to make the changes.

This seems very simple, and for the most part it is. However, there are certain times when things get a little bit tricky, and your strategy should define what needs to happen when things are not as straight forward as usual.

Source code changes might break the build or destabilize a feature. When that happens, you may choose to allow developers to keep submitting changes and hope for the best, or you may opt to lock your SCM database until a fix is found. Maybe, you decide on an option that lies somewhere in between. You may want to evaluate the situation and make a decision based on feedback from your build process, your development team, or the QA team.

Everything is good as long as your strategy defines what the procedure should be, your policies are consistent, and everyone buys into it. Otherwise, you will be making the decision when problems arrive, pressured by the current state of affairs, and with little understanding of the true impact of your decision.

Furthermore, the next time you run into a similar situation, you will second-guess your previous choices, and you will be tempted to handle things different. This will cause enormous confusion in your team and will increase the chances of someone making further mistakes.

You should plan for these situations, and your strategy should define how they will be handled. Allow your team to participate in the design of your strategy and listen how certain policies will impact their work, but always keep in mind that your source code and the stability of the product should come first.

2. Documenting Changes

We all know source code is going to change, but there is always a reason that triggers the change. We might be adding features, removing features, or fixing defects. Whatever the reason is, we, most likely, will forget about it in a few days.

Our Source Code Management strategy should define how we are going to document changes, so we can go back and review and understand what triggered certain change, how was implemented, and which source files were touched.

You may decide to use submission notes stored in your SCM or send an e-mail message to the entire team when a change is submitted. You may want to get fancy and create an RSS feed your team can subscribe to and receive the latest information about the on going changes to the project. Whatever you do, you need to define how changes will be documented.

I cannot tell you how many hours I wasted researching a problem going through useless submission notes because there was not a establish procedure on how to properly document a change. Most developers are very proud of their work and will spend as much time as needed documenting the changes they make. Most of the time. Until, they have to fix a critical bug the day after the application was released to create a hot-fix for an important customer.

During hectic times, good developers forget about many things, and the easiest thing to forget is to properly document changes because "in theory" it will not impact the end result. However, a few weeks after we release our hot-fix a new problem is found, we review the latest submission notes, and we cannot seem to find what might have caused the problem.

Evangelize about the importance of properly documenting changes. Create a standard template or form that will help your team to properly document submissions. Make it easy for everyone to document changes so your team can see the value.

3. Parallel Development

In any software development team bigger than, say... one developer, development occurs in parallel. Your team might be working on different features at once, work on new features might be done in parallel with the stabilization of completed features, or a team is working on the back-end of a feature at the same time as the UI layer. Parallelism is necessary to implement features quicker and more effectively.

What this really means is that changes in the source code are coming from every direction, and your Source Code Management strategy should plan for that. The bigger the changes are, like adding new features, the bigger the impact on the stability of a project.

You may decide to create separate branches for new features; you may decide all development should go to the same main branch. That is up to you to decide, but make sure your decision fits your needs and that everyone is clear on what the protocol is.

If you are using several branches for your parallel development, you must define how changes will be propagated between branches, who will be responsible for the integrations, and the exact procedure to perform a correct integration. You want to keep all active branches as close as possible to minimize integration problems. Your strategy should define under which circumstances a new branch should be created and when the branch will be considered closed for development.

Provide your team with guidelines that will help them stay as close as possible to the latest revision of the project. Ideally, they should stay as close as possible to the latest successful and stable build to minimize the impact of a bad submission on their work.

Invest on training. Provide your team with the necessary training on the SCM tools you use and make sure everyone understands and follows your strategy. Listen to your team on the policies that get on their way and make appropriate changes.

4. Rolling-Back Changes

So far, I have been talking about what you should consider and define when introducing changes in your source code. But most of the time, we forget to think about how we are going to roll-back a change that we made and is no longer necessary or caused more problems than it solved.

Your Source Code Management strategy should define how changes will be reverted. This is a tricky operation because sometimes it is hard to know what the status will be or should be after we perform the roll-back. We should define a set of guidelines that will help performing this operation in a successful way, at least, most of the time.

Everyone in your team should know how to roll-back a change they made. Provide them with the necessary training to perform this kind of operations. Make sure they understand how the tools work, and they feel comfortable using them.

5. Going Back In Time

Just thinking about it gives me the chills. All of the sudden, someone thinks is a good idea to fix a problem in an old version of your software, and you need to go back in time, get the snapshot of your project from years ago, make the necessary changes, and release a patch for an older version of your product.

Well, if your Source Control Management strategy has not planned for that, you are probably going bananas right now. You might get lucky and a simple "sorry, we cannot do that" will deviate the attention to more important tasks like getting the next release out the door. Sometimes, luck is not on your side, and your favorite sales person has already promise the fix to an important customer who cannot wait for your next release which contains the fix.

You should be able to go back to any point in time (or at least any important point in time), and retrieve the exact snapshot of your application back then. Probably, this is not the only thing you need to do, but it is a good start. If you have not defined a strategy that allows this kind of operation and proved that it will work, the chances of success are zero, null, none.

Always consider the most extreme cases and plan for them. They probably never happen, but when they do, you will be glad you have a plan.

6. Natural Disasters

Last, but not least, your Source Code Management strategy should define the policies by which your source code will be kept safe under any circumstances. Hard-drives crash, servers go down, and once in a while Mother Nature plays a trick on us.

It is your responsibility to define a back-up strategy, but most important, it is to define a restore strategy that you know it works. You can have all the back-ups in the world, but if you are not able to restore from them, they are basically useless.

Things can go terribly wrong. When that happens, we feel the pressure on our shoulders, we cannot think clearly, and it seems the world is about to end. It is not the best time to think. If we have a plan, we stick to the plan. Hopefully, we also tested the plan before we put it into practice, and we are comfortable enough it is going to work. We still feel the pressure and the adrenaline rush, but we know there is light at the other end, and it feels good.

Conclusion

The source code you produce is the most important asset you have. You have to define how you are going to manage it, and how you are going to keep it safe. A consistent strategy will help your team to follow the correct procedures under any circumstances. Your team should provide you with feedback on what is working and what is not, and you should listen and evolve your strategy to insure guidelines are improved and followed.

Needless to say that an SCM system will help you manage your source; that is what SCM systems do, but you and your team should be the ones deciding which tools are good for your situation. When you decide, make sure everyone in your team is properly trained on the tools you are using. Also, make sure they actively participate elaborating your strategy. Talk to them and do not be afraid of changing policies that are not working. People learn from experience, and it is almost impossible you will get your strategy right the first time around.