Productivity tools and tips for researchers

Productivity tools

Jabref

Jabref is one of the simplest and very useful tool for managing the references. Maintaining a bib file without a reference manager software is very cumbersome. Reference manager can help in avoiding the duplicate entries or assigning same key for multiple references. It can also help you to easily sort the references as per your need. In Jabref, we can link the pdf files with each reference entry and access them just by clicking pdf icon on the left of the entry. The tool makes it very easy to search any reference in a big list of references. There are various other tools available freely like Medeley, Endnote, zotero etc. for managing the references. Click here to get some usage details about Jabref.

Version control

When we do a project over a long time (over months), we keep on writing program and modifying the old programs. We have the confidence that the old work is done well and we can reproduce those results at any point of time. However, such assumption may not be correct as we keep on modifying the old files to make them more useful. Hence it seems it is a good idea to keep a copy of old working programs in a separate archive and then proceed with new ones. Sometimes, we face another problem. We suddenly find the new programs are not working. They have been modified unknowingly in an inadvertent way by ourselves or by computer corruptions such as virus attack. Hence we have no other way but to start afresh. However, if we have the intermediate files, we could save a lot of work. But, how many intermediate copies we can make and how to keep them in a proper way so that we can access them easily? While writing software project we run into another problem when multiple peoples are involved. To develop a new functionality, we often need to modify a bit the old files. When two or more people are working on the same project we ask them to work on different features or modules to minimize such clashes. However, still they are using same old files and if there is any change, it affects the other developers badly. Hence, we need to process to streamline these issues. The process which helps us to do it is known as version control.

Version control is very important for storing the various versions of code and to switch between the versions of code as per the requirement. Some of the reasons to consider using version control system:

* Made a change to code, realized it was a mistake and wanted to revert back?

* Lost code or had a backup that was too old?

* Had to maintain multiple versions of a product?

* Wanted to see the difference between two (or more) versions of your code?

* Wanted to prove that a particular change broke or fixed a piece of code?

* Wanted to review the history of some code?

* Wanted to submit a change to someone else's code?

* Wanted to share your code, or let other people work on your code?

* Wanted to see how much work is being done, and where, when and by whom?

* Wanted to experiment with a new feature without interfering with working code?

There are number of tools for version control viz. Souresafe from Microsoft, Cleasecase from Rational IBM and CVS. CVS is a command line interface package. To make it more friendly different GUI have been designed. To make use of CVS we have to consult the tutorials (1,2,3). WinCVS is one of them. Another popular CVS interface is TortoiseCVS, which is very easy to use from Windows platform. One of the most famous tools is GIT. For the Introduction to GIT, you can refer the ppt given here. The details about its usage are given here. Some most frequently used commands are given here.

Data Backup

Data backup is very important for keeping your data safe. In case of hard disk crash or OS crash or virus attack, we lose our vital data and/or codes. So, it is necessary to take the backup of the data regularly at-least once in a week. The 'Sync Toy' is the software which is very handy and convenient to use for taking backup of the data. The usage details is given here.

Software Programming Tips

If you know a computer language (or platform like Matlab), then we think anyone can do programming. We have to just sit at a computer and write a program very much like stories or an email. I hope you agree with me. But, are we doing it efficiently? I mean that are we saving our time and effort in this way? To save your time and effort and to make the experience pleasant for a long time we have to follow the path discovered by people before us. They have found them by their hard work and experience we can just follow them. The rules are simple. The first task is to sit with a pen (pencil) and paper, make it clear what we want to do and the steps required to follow for it. Then we are in a better position to quickly write the program. There is a fancy name for this first step. It is called requirement analysis and software design.

Design:

Rather than going into them, let us appreciate that a bit of clear understanding and homework helps us to save our time and effort. For example for scientific programming, we should have the governing equations at hand. Then we should make a sketch of the work and flow chart or block diagram is a good way towards it. We notice that for any program we start with reading some parameters and data (signal/image) and then we go through the steps of operations which ends with writing the results (parameters and data) in one or more files. Hence it is a good idea to keep in a program (file) and the operations in separate files. These operations or processes may be changed from program to program and they can be reused in future. Hence, it is a good idea to write them in the separate file(s), which will make it easy to use them on demand. Figure1 illustrates this concept in a lucid manner. At this point, our task reduces to take care that the subroutine/function interfaces i.e. to take care of the input and outputs so that no incompatibility crops up later. Interested readers may read any book on Software Engineering for more details.

Documentation:

After writing the code and testing it we feel our work is finished. However, the truth is far from it. As we live with software (or rather we cannot live without it) we have to keep them healthy to keep ourselves free from worries and trouble. Here are small tips on it.

To use the code over a long period we should comment the code properly. Software engineer calls this as "Code Documentation".

Without code documentation, other people can not understand and maintain the code. Hence without documentation, a code is of no value. Here is some direction for code documentation.

Matlab code documentation

We should write help for each of the Matlab code. It is a good way to capture most of the useful information about the code. A template of the help is given for your perusal. Within the code, we can put our comments to make it more readable. It is easier to appreciate these points from the examples: swap_script.m and swap.m written for you.

Sample presentation of step by step methodology to document a code in MATLAB platform is given in here.

High-level Language code documentation

The spirit and format for code documentation remain the same as described in the previous section. Over and above we get the help of some tools which can create very neat separate documents on the code from a properly documented code. The steps are like this. We have to document the code as before. The only thing we need to keep in mind is some tags (just like HTML tags) while writing the comments in the code. Then the tool runs on the code to generate code document in HTML. They can also capture the class diagram and the class hierarchies in the case of object-oriented language. Doxygen and Javadoc are few examples of such tools. While Javadoc works for Java Programs only, Doxygen can work on C, C++, Java and many other languages. To know more about them you should follow the examples and tutorial.

Java Example Program and excerpts of Doxygen generated document

C Example Program and excerpts of Doxygen generated document

C++ Example Program and excerpts of Doxygen generated document