Skip to main content

Posts about software

Error messages and new users

I was helping a friend of mine setup his blog and we were trying to use Hexo – a static site generator. We chose a Javascript based tool since he's trying to learn Javascript. I skimmed through active Javascript projects in this list and finally zeroed down upon Hexo based on its popularity. I promised to help my friend to set this up, but he first tried to do it on his own and got back to me after an hour or so, quite frustrated and almost on the verge of giving up setting it up. I didn't expect this from a tool that had so many stars, forks, plugins and so much active development.

We finally got it working, but we found that the error messages were horrendous – even for someone who has been using free and open-source tools for a while now. Printing out errors from compiler or interpreter directly along with the stack trace is almost always the worst thing to do for a tool/utility (as opposed to an API or library). The stack trace is definitely useful, for developers trying to build upon or improve your tool. Have a debug or development mode where developers can get all the information they need.

If you care about your users, especially new users, make sure you spend sufficient time on showing human-readable messages. If possible list the possible causes for every error along with tips for troubleshooting.

Learning about Spaced Repetition, SuperMemo, Org-drill, et al.

I have been reading a bunch of articles on the SuperMemo site (including the original thesis of P. A. Wozniack, the creator of SuperMemo). I initially started off trying to understand the algorithms SM2,5 and 8 which org-drill implements, but reading the articles has given me a lot of general background and theory on how memory works, and why SuperMemo is as effective as it is (for those who stick with it). This blog post is an attempt to summarize and capture what I have read in all those articles, and not get lost in them. I would recommend reading the thesis and the suggested reading there, yourself, but if you really don't want to – this blog post + the summary in here, and here would be a good alternative.

  • Memory works by repetition. Each time you recall a fact, the time it takes for the memory to fade increases. Spaced repetition is the idea of repeating items, just when you are about to forget them – trying to optimize the time spent on learning, as well as the retention of learned material.
  • Prioritization of the items we need to learn is key to being able to stick to Spaced repetition. Beginners tend to be over-enthusiastic about the technique and fill up their system with stuff that they don't really care about. Applicability of the knowledge you are trying to gain, is a good test for whether or not it goes into your system.
  • Each version of SuperMemo comes with a slightly modified (on most occassions, improved!) algorithm. SM2, SM5, … refer to these algorithms. Org-drill currently supports only sm2,5 and 8. It may be worth looking at sm15/16 and seeing if it can be implemented and is worth doing. In any case, using any of these is way better than not using Spaced repetition at all.
  • Understanding what we are trying to learn goes a long way in helping memory. It is, therefore, good to start with basic material. People have been surprised by how easily the advanced stuff fell into place, once they had the basics covered.
  • Keep items in the system simple. Stick to the minimum information principle. Keeping it simple, doesn't mean you leave out on learning the complex stuff; instead break it into simpler components. Simpler items has the following advantages:
    • Simple is easier to remember.
    • Simpler items are easier to schedule. You get more resolution to figure out what the problem areas are.
    • Simple makes brings in redundancy automatically. And redundancy is good for memory, just like it is for managing hardware failure.
  • Keep learning fun! Don't make review sessions a chore. Think about the material you are reviewing. Edit/delete/improve items based on your reviews, then and there. Stay active.
  • It is useful to add a link to the source of the items added to your system, considering that you wish to use the system over a long period of time (ideally, the rest of your life!)
  • Prioritize, add examples, appeal to your emotional state, link to existing knowledge, use images. Anything else that works for you! Use all of these techniques, that work well and you probably already use in everyday life, in the items you add to your system, to make them easier to recall.
  • Being physically fit and healthy is important for being so mentally. Exercise, sleep, eat well, avoid caffeine.
  • Try incremental reading, as an input source of items into your memory system.

Learning to use Org-drill

Org-drill is an Org-mode extension that provides spaced-repetition and flash-card functionality. It has a wonderful documentation on Worg, but somehow I couldn't get myself to read the whole document, and setup org-drill, until now.

The setup is quite straight forward, once you have org-mode along with the contrib packages. Just (require 'org-drill), and you are all set! To add a new card, all you need to do is add a :drill: tag to the items you wish to "Org-drill". You can start a review session with simply M-x org-drill. You will be shown flash cards, and you can rate how correct and comfortable you were, in answering the questions. Based on your responses, the cards are scheduled for review. Start another review session, whenever you need one!

What I could only understand once I got myself to read the whole document was that:

  • The default scope of a drill session is the current file. But, you can start sessions with scopes like current tree, current directory, or a specified list of files. This is super-useful!
  • The review sessions are not automatically scheduled, based on when you schedule failed flash-cards. Scheduling the review for a card only sets a due-date for them, and effects, what you are asked in your next session.

Cram mode and incremental reading are also things I want to try, as I go along.

Happy Learning!

Best Practices for Scientific Computing

Shantanu and I gave a short talk titled "Software Carpentry for Scientists" for the graduate students of Chemical Engineering department, IISc, this Friday. We gave a short introduction to Git, TDD, Numpy/Scipy, etc and mentioned a few things from Greg Wilson et al's paper.

I promised to revert to them with links to a few resources. I figured it would be more beneficial, if I just put it in a publicly available place.

A summary of the paper by Greg Wilson et. al., is below.

Summary of paper by Greg Wilson et. al.

  1. Write programs for people, not computers
    • a program should not require its readers to hold more than a handful of facts in memory at once.
    • names should be consistent, distinctive and meaningful.
    • code style and formatting should be consistent.
    • all aspects of software development should be broken down into tasks roughly an hour long
  2. Automate repetitive tasks
    • rely on the computer to repeat tasks
    • save recent commands in a file for re-use
    • use a build to automate scientific work-flows
  3. Use the computer to record history
    • software tools should be used to track computational work automatically.
  4. Make incremental changes
    • work in small steps with frequent feedback and course correction
  5. Use version control
    • use a version control system
    • everything that has been created manually should be put in version control
  6. Don't repeat yourself (or others)
    • every piece of data must have a single authoritative representation in the system
    • code should be modularized rather than copied and pasted
    • re-use code instead of rewriting it
  7. Plan for mistakes
    • add assertions to programs to check their operation
    • use an off-the-shelf unit testing library
    • use all available oracles when testing programs
    • turn bugs into test cases
    • use a symbolic debugger
  8. Optimize software only after it works correctly
    • use a profiler to identify bottlenecks
    • write code in the highest-level language possible
  9. Document design and purpose, not mechanics
    • document interfaces and reasons, not implementations
    • refactor code instead of explaining how it works
    • embed the documentation for a piece of software in that software
  10. Collaborate
    • use pre-merge code reviews
    • use pair programming when bringing someone new up to speed and when tackling particularly tricky problems
    • use an issue tracking tool

3 tips for those shipping (commercial) apps

Here are some very generic (and paraphrased) notes from a short talk today, by Deepankar Sharma.

  1. Whenever you release a new major version, make sure you keep a copy of the whole "ecosystem" to be able to run it whenever you want. At any point in time, you should be able to run any version of your software.
  2. When writing benchmarks/tests/etc., try and ensure that you cover a broad spectrum of test data, to try and replicate the different types of data that users could possibly have.
  3. Don't develop applications with modes. Be very careful before you add a new mode to your application, effectively adding one more code path to maintain.
  4. (Bonus) Beware of too much extensibility

GetHub: Chrome Notifications for Github updates

Over the last two days, I hacked up my first Chrome extension. I've been using Chrome only for the past couple of weeks or so and I begin to like it, though some of the extensions aren't as mature as I would've liked.

The original idea was floated by my friend, Madhu, and Lee helped me quite a bit, while I was working on it.

What does it do?

It is a simple extension, that shows pop-ups, whenever there is an update in your GitHub "Wall" (yes, this is a Facebook world) or News Feed as they call it.

After installation, you will need to save your username and token for the extension to work.

Where to get it?

Presently, you will need to get it from GitHub.

I might add it to the Chrome Web Store, once I see more people using it. I couldn't justify, to myself, paying the initial one-time verification fee that Google asks for.

UPDATE: [2011-03-04 Fri] Added GetHub to the store

Comments and Feedback

  • Feel free to write to me at
  • Or file issues at GitHub.

Happy GitHubbing!

Richard Stallman in IIT-Bombay

RMS will be in IIT-Bombay on the 6th of this month. He will "speak about the goals and philosophy of the Free Software Movement, and the status and history of the GNU operating system, which in combination with the kernel Linux is now used by tens of millions of users world-wide. "

  • Date: 6th September, 2010
  • Time: 8:30 P.M
  • Venue: PC Saxena Auditorium, IIT Bombay

Sage Days 25, Mumbai, India

What is 'Sage Days'?

Sage Days is a confluence of present and prospective SAGE Users and Developers. It is an opportunity to come together to share ideas, brainstorm and hack on Sage. Sage Days 25 is the 25th version of Sage Days, and is being organized in Mumbai, India. In order to cater to an Indian audience and scenario, this version has been tweaked slightly. Sage Days 25 has beginner level tutorials, in addition to the usual talks and sprints, to help new users get started with Sage and help promote the use of Sage in India.

What is Sage?

Sage is a free, open-source mathematics software system licensed under the GPL. It combines the power of numerous existing open-source packages into a common Python-based interface. It's mission is to create a "viable free open source alternative to Magma, Maple, Mathematica and Matlab". Sage has tools for a broad range of mathematical areas like Linear Algebra, Calculus, Symbolic Math, Plotting, Rings & Groups, Graph Theory, Number Theory and Cryptography. Essentially, "it can do anything from mapping a 12-dimensional object to calculating rainfall patterns under global warming" - as Science Daily puts it . Eager to get started? Start here. Apart from being feature rich, it's usability is one of it's greatest strengths. Sage Notebook, a web-interface for all the math you'll ever want to do, is really the killer feature! As the Sage Marketing page says, "The SAGE GUI surely works on your computer box, because it just runs in Firefox!". Try it Now!

Why should you attend?

Sage Days 25 is being attended by the creator and lead developer of Sage, Prof. William Stein. It will also be attended by other developers of Sage. This would be a great opportunity to meet and interact with them! The conference will be attended by a plethora of enthusiastic people from all over the country who use Sage or are interested in doing so. The conference will also see the presence of many mathematicians interested in software. Who knows, you may run into someone you'd want to collaborate with, for your future work! This event will be a great learning experience, if you are even remotely interested in math and software for it!

When and Where?

  • Venue: IIT-Bombay, Mumbai, India
  • Dates: August 9-12, 2010
  • Tentative Schedule
  • Register Here
  • Click here for more info

Software Freedom Day

Three Cheers to 'Free Software'!

A toast for GNU on its 25th Birthday!1

If you intend to ask, what I did on this day, I have nothing to show. I haven't done anything that's tangible but yes, I have re-dedicated myself to the idea of Free Software. This post intends to shed some light on a few things (if not for the benefit of others, just as a reminder for myself)

  • Free Software is a matter of liberty, not price. I've often been in a position that required me to correct people. 'Free Software' is software that's free as in free speech and not free beer. For the lack of a better word in english, the word 'free' which also means gratis has been used. Using the term 'Libre' sometimes helps and if you are in this part of the world, "mukt" is the best word to use.
  • Free Software2 comes along with four fundamental freedoms. To put it simply, the freedom to use, study, share and modify any software.
  • Free Software may have the advantage of being 'technically sounder', but the philosophy is what matters the most to me.
  • I will do whatever is possible within my capacity to spread the philosophy and the associated freedom

Be Free, My Friend!

Here is an extract from one of Stallman's 3 essays:

We must talk about Freedom

Estimates today are that there are ten million users of GNU/Linux systems such as Debian GNU/Linux and Red Hat Linux. Free software has developed such practical advantages that users are flocking to it for purely practical reasons.

The good consequences of this are evident: more interest in developing free software, more customers for free software businesses, and more ability to encourage companies to develop commercial free software instead of proprietary software products.

But interest in the software is growing faster than awareness of the philosophy it is based on, and this leads to trouble. Our ability to meet the challenges and threats described above depends on the will to stand firm for freedom. To make sure our community has this will, we need to spread the idea to the new users as they come into the community.

But we are failing to do so: the efforts to attract new users into our community are far outstripping the efforts to teach them the civics of our community. We need to do both, and we need to keep the two efforts in balance.



The Free Software Definition


The GNU Project by Richard Stallman