Recommended Development Environment (Tutorial)

With the goal of standardizing to the maximum the workflows, HERMES proposes a list of tools to be used for the development of source code. Respecting these guidelines will guarantee that you can benefit from the software tools of the platform, while also making your own code easier to reuse by others.

This guide is written to cover the need of a vast majority of the laboratory population. However, if you feel that for your project you will need to use different tools, do not hesitate to contact us. We are available to advise you on the best choice of tools for very specific projects.

Programming Language

The programming language recommended by the HERMES platform is Python. There is a chance that you are a consolidated Matlab user, and you wonder why should you change to Python instead of continuing to use Matlab. The answer is quite simple: Python allows you to do all that you can do with Matlab (and even more!) without the need of paying for a license. Opting for Python does not only allow your laboratory to save money (which can be used to found other resources), but it also makes your code accessible to any person in the world. Using (and creating) open source software tools for our work, makes our research closer to the open science practices encouraged by the European Union and other organizations.

You may be concerned about the performance of Python code, since perhaps you have someone claim that "Matlab is specifically tailored for linear algebra operations". It must be taken into account that Python presents a library called NumPy conceived for linear algebra operation. This library is coded internally in C, which means that by using it your Python code can be as efficient as Matlab's, as shown here and here.

Moreover, there are also libraries for the generation of plots (Matplotlib) and for common tasks like optimization, interpolation or integration (SciPy) which will cover all the need that you may have for conducting your research.

The good news is that you are already used to code using Matlab, making the transition will be quite easy, since the syntaxes of both languages are quite similar. Here you can find a guide which will help you to change from one language to the other.

Although you can directly go to the Python site and download a Python interpreter from there, for a research environment it would be preferable to download a Python distribution which already contains all the aforementioned libraries, instead of installing pure Python and then manually downloading the libraries one by one. A good recommendation of a Python distribution is Anaconda. This tutorial, will show you how to install Anaconda on your computer.

Integrated Development Environment

An Integrated Development Environment (IDE), is a software application that combines several tools for the creation, testing and debugging of source code. An IDE typically integrates a text editor with syntax highlighting capabilities, a compiler or interpreter and a debugger among others.

Chances are that you may have already used an IDE in the past (although perhaps you didn't referred to it by this name). For example, if you have written Matlab code, you will have probably used the IDE provided by Mathworks. Although it is perfectly possible to develop software without using an IDE, its use vastly simplifies many steps of the development process.

There are many different IDEs that can be used to work with Python. At HERMES, we recommend two of them Visual Studio Code (VSCode), and Spyder.

The main strength of Spyder is that it has been designed to replicate as much as possible the interface of the Matlab IDE. In addition, installing Anaconda on your computer will also instal Spyder, giving you a functional IDE out of the box, without the need of configuring anything. Nevertheless, Spyder is far more limited in its customization, and also in does not present a complete integration with Git.

On the other hand, VSCode is a general purpose IDE which can be used to work with many different languages (not only Python, as it is the case with Spyder). In addition, VSCode can be customized up to a very high degree thanks to the use of extensions, installed via an extension manager integrated in the IDE. These extensions can add support for different programming languages, integration with Git, autoformatting of the code, etc. Moreover, thanks to these extensions you can even compile and visualize Latex documents in VSCode, which allows you to use the same IDE for processing your data a writing your papers! However, this greater flexibility requires that the user configures the IDE before being able to run its first script.

If you are more or less used in fiddling with software tools, or if you haven't ever used Matlab, we recommend that you begin directly with VSCode. Since you will have to make an effort anyway to use either VSCode or Spyder, it will be worthy learning to use VSCode since you will be able to use it for many languages.

If, on the other hand, you are very attached to the Matlab IDE, and you do not feel very comfortable working with new software tools, Spyder can be a good option for helping you transitioning to the Python ecosystem. Later, when you are more familiar with Python, you can make the transition to VSCode to benefit from its higher customization capabilities.

In case that you choose to use VSCode, it is recommended that you install the following extensions:

• Python: Adds support for Python to the IDE.
• Pylance: Adds language support for writing Python.
• Python Debugger: Adds support for debugging Python code.
• Jupyter: Adds support for Jupyter notebooks and interactive code execution.
• autoDocString: Adds templates to create DocStrings for the implemented functions and classes.
• Python Indent: Automatically corrects indentation in Python code.
• Git Graph: Adds a visualization of the Git log.
• Rewrap: Automatically adds lines breaks to comments when they exceed a certain line length.
• Code Spell Checker: Spell checker for comments and variable names.

Version Control System

What is a Version Control System?

Version Control Systems (VCS) are tools used in software development to track and manage changes to the code. These tools allow to create a snapshot of the project every time that a modification is implemented. Thanks to these snapshots, one can navigate through the history of the project to correct bugs or recover pieces of code that were deleted by error.

In addition, most VCS also implement tools that facilitate the collaborative development without conflicts, even if several people try to modify the same part of the code.

Why do I need a Version Control System?

• Avoids losing any changes, since we can always roll-back to a previous version.
• Allows to see who and why made a certain modification, which simplifies the debugging process.
• Typically, VCS offer a way to backup the code in a remote server.
• Thanks to the branching and merging capabilities of a VCS, it is possible to implement a new feature of the code without modifying the last stable version. And integrate the modifications once that they have been finished and tested.
• A VCS allows several developers to work in parallel on the same project, and provides the tools for manage the conflicts that may arise if the modify the same parts of the code.

I already use Dropbox / Google Drive / OneDrive do I really need a VCS?

Absolutely yes!

Although these tools serve to back-up files on a remote server, they do not serve the same purposes as a VCS. One of the main reasons is that we, as users, do not have any control on when the snapshots are created. When using a VCS, we want to create a snapshot once that a certain modification has been implemented, and not every X minutes or once that we save the file.

More over, in the spite that these tools save a list of former versions of their files, navigating through the history of a project is impossible, since they typically store a separate list of modifications for each individual file. These means that if we would like to roll back the project to a former state, we would need to identify the appropriate version for each file individually, and restore them one by one. In any real world project with several code files this is an impossible task. Moreover, since these file syncing tools are not VCS, they do not provide a way to add comments to their snapshots (as VCS do) to help identifying them in the future.

It is also worth noting that, even if these services store a certain history of the files, this history is by no means conceived as a permanent storage. Therefore, oldest revisions are deleted as newest ones are created.

Finally, even though these services implement some tools for collaborative document editing, these are not conceived for collaborative software development. The modifications made by one user are seen in real time by all the other users. This is by no means something desirable in a context of collaborative development, since the modifications temporarily made by one user to a certain file, may render the project unusable for the others. On the contrary, a VCS will allow a certain user to implement her modifications on a separate branch, and integrate them to the common copy of the project once that they have been finished.

In conclusion, despite tools like Dropbox, Google Drive, OneDrive and others can be useful in certain contexts, they have not been conceived to be a VCS, and therefore they cannot replace them. In addition, it is worth mentioning that a project managed by a VCS should by no means be backed-up at the same time using one of these tools, since the VCS and the file synchronization service may conflict with each other.

Which Version Control System is recommended?

The VCS recommended by the HERMES platform is Git.

Git is open source, cross-platform and extremely fast and efficient compared to other VCS. All this reasons, make it the *de facto* standard in the world of software developing.

VCS server

On its own, Git will allow you to manage a repository locally on your computer. However, if you want to back-up your code to a server and share it with other colleagues, you can use the GitLab instance hosted by the CNRS.

To login to this platform, you can use your Janus identifier. If you do not have a password yet (or if you have forgotten it), you can click on "Mot de passe oublié" and follow the instructions.

In order to learn how to connect your local repository to the server, you can follow this tutorial.

GitLab does also provide a fair amount of tools to ease the collaborative development. You can learn more about this by reading the tutorials about the recommended workflow, and the use of GitLab for collaborative development.