A blog about design, code and some other stuff

Lately I’ve been avoiding inline documentation specially because JavaScript is a very loose language and I feel that inline-docs add too much noise to the code… But since documentation is very important if you want other people to use your code or if you have a large codebase I decided to create a simple documentation generator using nodejs to parse external markdown files. I tried to find other tools but none of them had all the features I wanted so I decided to code mine.

So far it’s a little rough around the edges, code can be cleaned a lot (I coded it really fast) and it isn’t as flexible/polished as I want it to be, but it’s working fine for my current needs.

The project is on Github and repository contains some example files with comments, you can check the amd-utils documentation for a live example - amd-utils documentation uses a custom template but it’s very close to mdoc default template, only extra feature is the “specs” and “source” links (since other projects probably have a different file/folder structure).

I’m not sure when I will have time to improve it but I already added a couple feature requests to the issue tracker. Watch it, fork it and contribute! If you want to report bugs and feature requests please use the Github issue tracker.

That’s it!

If you know Number Theory or had algorithms classes in college you can probably skip this post… - I studied Graphic Design so I had to learn those things by myself - I will try to explain it using as less math as possible.. I know there is a lot of info about this subject on the internet and algorithms books but today I spent a couple minutes searching for it and most of them are too hard to understand if you are not a mathematician (which BTW I’m not..) so after giving up on the hard reading I decided to come up with my own solution to the problem, it may not be most elegant solution but it is at least a logical solution and results are acceptable.

Read more…

Last week I released a new version of js-signals, I usually avoid creating posts at each release since I think people can simply watch the project on Github or are already following me on twitter (and I always send a twit after each release) but I added a few “advanced” features that may be useful on specific cases, that’s why I decided to create a post about it, I think some explanation may help people identify good use cases for those features.

Read more…

This post is very polemic, I thought a lot before publishing it, please try to be open-minded and read the whole thing before commenting, it is not supposed to become a flame war. Please read the about page to understand the objective of this blog and the way I think about it.

I’ve been considering to use a CSS pre-processor like SASS, LESS, Stylus, etc, for a very long time. Every time someone asked me if I was using any of these tools/languages I would say that I’m kinda used to my current workflow and I don’t really see a reason for changing it since the problems those languages solves are not really the problems I’m having with CSS. Then yesterday I read two blog posts which made me reconsider my point of view so I decided to spend some time today studying the alternatives (once again) and porting some code to check the output and if the languages would really help to keep my code more organized/maintainable and/or if it would make the development process easier (also if they evolved on the past few years).

Read more…

Been delaying to write this post for a long time, I think it’s something that experienced developers or people coming from strong typed languages like Java or C# probably already know what I’m going to talk about but for JavaScript developers I think it will be an important information since everyday I see someone (or some famous open-source project) doing it “wrong”.

Strings are evil

Strings are error-prone, a small typo error and your application won’t work as expected and the compiler/environment/VM/etc probably won’t give you any error messages, consider the code below:

    calendar.showMonth('feburary');
    calendar.dispatchEvent('monht/show');

Did you noticed something wrong? “February” and “month” were misspelled, depending on how the code is written you won’t see any error message and have no idea why the month isn’t being displayed and why the event listener isn’t being called…

Read more…