Asynchronous Tasks with Elixir
One of my first contributions into ExDoc, the tool used to produce HTML documentation for Elixir projects, was to improve the documentation build process performance. My first approach for this was to build each module page concurrently, manually sending and receiving messages between processes. Then, as you can see in the Pull Request details, Eric Meadows-Jönsson pointed out that I should look at the Task module. In this article, I’ll try to show you the path that I followed to do that contribution.
How to document your Javascript code
Someone that knows something about Java probably knows about JavaDoc. If you know something about Python you probably document your code following the rules defined for Sphinx (Sphinx uses reStructuredText as its markup language). Or in C, you follow the rules defined for Doxygen (Doxygen also supports other programming languages such as Objective-C, Java, C#, PHP, etc.). But, what happens when we are coding in JavaScript? How can we document our source code?
As a developer that interacts with other members of a team, the need to document all your intentions must become a habit. If you follow some basic rules and stick to them you can gain benefits like the automatic generation of documentation in formats like HTML, PDF, and so on.
I must confess that I’m relatively new to JavaScript, but one of the first things that I implement is the source code documentation. I’ve been using JSDoc for documenting all my JavaScript code, it’s easy, and you only need to follow a short set of rules.
/**
* @file Working with Tags
* @author Milton Mazzarri <[email protected]>
* @version 0.1
*/
var Tag = $(function(){
/**
* The Tag definition.
*
* @param {String} id - The ID of the Tag.
* @param {String} description - Concise description of the tag.
* @param {Number} min - Minimum value accepted for trends.
* @param {Number} max - Maximum value accepted for trends.
* @param {Object} plc - The ID of the {@link PLC} object where this tag belongs.
*/
var Tag = function(id, description, min, max, plc) {
id = id;
description = description;
trend_min = min;
trend_max = max;
plc = plc;
};
return {
/**
* Get the current value of the tag.
*
* @see [Example]{@link http://example.com}
* @returns {Number} The current value of the tag.
*/
getValue: function() {
return Math.random;
}
};
}());
In the previous example, I have documented the index of the file, showing the author and version, you can also include other things such as a copyright and license note. I have also documented the class definition including parameters and methods specifying the name, and type with a concise description.
After you process your source code with JSDoc the result looks like the following:
In the previous image you see the documentation in HTML format, also you see a table that displays the parameters with appropriate links to your source code, and finally, JSDoc implements a very nice style to your document.
If you need further details I recommend you check out the JSDoc documentation.
Grunt: The Javascript Task Manager
When you play the Web Developer role, sometimes you may have to endure some repetitive tasks like minification, unit testing, compilation, linting, beautify or unpack Javascript code and so on. To solve this problems, and in the meantime, try to keep your mental health in a good shape, you desperately need to find a way to automate this tasks. Grunt offers you an easy way to accomplish this kind of automation.
The DRY principle
The DRY (Don’t Repeat Yourself) principle it basically consist in the following:
Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.
That said, it’s almost clear that the DRY principle is against the code duplication, something that in the long-term affect the maintenance phase, it doesn’t facilitate the improvement or code refactoring and, in some cases, it can generate some contradictions, among other problems.
libturpial needs your help
Do you want to begin to contribute into libturpial codebase but you don’t know where to start?, that’s ok, it also happens to me sometimes, but today, the reality is that we need your help to fix some errors reported by our style checker (flake8)