503 Service Unavailable

2007-08-29

Reporting Bugs

Filed under: Communication,Software — rg3 @ 20:31

Today I’m not writting about something new. On the contrary, I’m writting about a document that has been available on the net for years. It is, however, so well written and complete that it would be a mistake not to spend at least one post emphasizing its virtues and ignoring its faults. Yes, you’ve guessed it, it’s the essay How to report bugs effectively by Simon Tatham, the author of Putty. I’m talking about it now because some days ago Mr. Tatham accepted my Spanish translation of the document and it is now listed in his website, so it’s a good moment to dedicate some lines to the document, before I forget about it. By the way, I’m aware that the translation has a couple of mistakes that I will correct in order to send him a new version soon.

Not long ago I hadn’t created any open source programs that were available for everyone to use, but in the last years I have created a handful of small tools (I don’t think any of them surpasses 2000 lines of code) that have become a bit popular, especially youtube-dl (which, by the way, is only 405 lines long at the time I’m writting this). youtube-dl has a number of users in the thousands, I think, and the number of emails it generates is much bigger than for any other tool. So far, my *-dl mail folder (dedicated to emails about youtube-dl, metacafe-dl and pornotube-dl) has about 400 messages, and this has given me a good amount of first hand experience in user emails. The style and contents of those emails is quite varied. There are a number of them that simply thank me for creating the program. I try to reply to every one of them and thank them for their support, because it’s very nice. I’ve written a few emails to exclusively congratulate the people responsible for a program, and the emails I received motivate me even more to continue doing so, because now I know how much appreciated those can be.

On the other hand, the most common type of email is the bug report or help request. Of those, some of them are very polite and share the same style I normally use. Let’s call them congratulations-however emails. Let’s see: “First off, thanks for creating blah. It’s a great tool and blah. However, I hit the following bug and blah blah blah.” That type of reports is also well received on my side, even when the bug does not really exist or is a user problem or temporary problem that the user identified as a bug.

Some others leave a lot to be desired. Starting by the people who don’t thank you, nor in advance nor after receiving your reply. There are a good amount of these cases. People who write you, for example, about a specific problem they’re having to make your program work. They contact you, they explain the problem as detailed as they can and you take a lot of time to write them a step-by-step guide that even a drunk monkey could follow. Then, silence. Not even a reply thanking you for spending 10 minutes on their problem. Maybe it’s only me, but if I have a problem and someone gives me a long reply trying to explain what the problem is and how to solve it, the first thing I do is to reply thanking them for their time and their efforts to enlighten me, even if that was a complete failure or the instructions weren’t helpful or I didn’t understand a word of what they said. I’d feel bad otherwise.

The worst type of emails are the bug reports that say nothing, do not mention the problem and, on top of that, are so poorly written (by English speakers) that I can barely understand a word of what they say. Or maybe they report about a possible problem with the program and when you request more information they go silent, which leaves you expecting a reply. Maybe you’re even delaying a release in order to fix the possible bug in time, but you have to release it anyway 3 days later because they don’t reply.

So the majority of bug reports and help requests are not as useful and clear as they should be. I think every computer user should spend 10 to 15 minutes reading Simon Tatham’s essay. Really, it looks long but that’s the time it takes to read it. It covers almost every aspect of reporting a software bug or technical computer problem, and those aspects are all explained in detail. It gives all the whys and hows and is very easy to understand. In fact, it’s so complete that parts of it can be extrapolated to other situations like when you’re reporting problems to a system administrator instead of a programmer. To complete it a little bit, given that it explains in detail how to report bugs, I’d mention the why. It’s important to report bugs. Bugs may not only affect you but also other users of the same program. When the program doesn’t have a bug-tracking facility, the number of reports the programmer receives about a bug is a measure of how many people are experiencing the problem and how frequent it is. It lets the programmer concentrate on solving the most important bugs first. It doesn’t matter if you are a clueless user that has problems explaining things. If you lack knowledge and vocabulary, you can replace them with detailed descriptions. It doesn’t matter that you say “I clicked on the Edit word next to File at the top of the program, just below the bar that has the X icon to close it” or “I clicked on Edit on the menubar”. So it doesn’t matter that you don’t know what a window, window border or menubar is. If the bug report is detailed enough, anybody can understand what you say, and anyone who reads your report will appreciate your efforts to write it and is more likely to lend a hand to make you and other users happy.

Now, please, go and read the essay. Really. It may even be available in your first language. :)

2007-08-28

Flash Cookies

Filed under: Software — rg3 @ 14:46

Yesterday I found out something quite interesting while reading a thread at LinuxQuestions.org. Summary: the flash browser plugin lets flash applications store information persistently on your hard drive. Sorry if this is common knowledge, but I didn’t know it and I’m quite shocked. That information can (may or may not) be used as browser cookies, as the thread shows. These days many people take their cookies seriously, maybe disabling them or deleting them from time to time or adjusting the browser cookie settings so it considers every cookie a session cookie that should be deleted when the browser is closed. Now, you need to be aware of a new battle front. Under Linux (and probably other Unix systems), these pieces of information are stored under $HOME/.macromedia/. Run find ~/.macromedia -print to get an overview.

I remember one of the reasons people started to care about cookies in the first place was that sites like doubleclick (recently bought by Google) would serve ads for thousands of websites on the net, and those ads would store a cookie in your hard drive identifying you, so they could in theory track what you visited on the net and build a profile. Today the problem would still exist because sometimes ads are served in flash format.

You can, however, configure the flash plugin so it doesn’t let anybody store anything in your hard drive. It must be noted that to do so you must visit macromedia.com and adjust the plugin settings from a flash application that is available on their site. Moreover, if you completely disable data storage, you are warned that some sites may stop working. Amazing. So this problem is hard to avoid. My personal recommendation is to use a browser plugin like the typical FlashBlock for Firefox or the “Load plugins on demand” setting under Konqueror, so every flash application is blocked unless you specify otherwise. And, you may want to delete the $HOME/.macromedia/ directory from time to time, or at least part of its contents (settings are also stored in that directory). It’s also worth mentioning that the settings and data are cross-browser, obviously. They are stored by the flash plugins no matter what browser you’re running the plugin from.

It’s a shame so many websites require flash for basic browsing, as well as the lack of a flash plugin for many platforms. The plugin could also have an option to delete any hard drive data when closing it, similar to the option to treat all cookies as session cookies that many browsers feature.

2007-08-23

Tabs versus spaces: let the flame begin

Filed under: Programming — rg3 @ 17:29

If you want to discuss just for the sake of discussing about something with your fellow programmers, just ask if tab characters are a better way of indenting code than spaces. People will start pointing out the pros and cons of each method, and can easily become very passionate about the method they use and enter a quite heated discussion on who is right and who is wrong, which method is more practical and which one is not, which is The Right Thing and why the followers of other methods should be shot down.

When you work alone it doesn’t matter. You cook it, you eat it. The problem comes when you have to collaborate with other people and you need to view and edit their code, and not everybody uses the same editor with the same settings.

Back in the old days everybody edited their code indenting with tab characters, which is typically represented as an 8-spaces wide gap. But in many modern languages, that space is just too much. The language itself makes the typical indentation level deeper, and the convention today is to use longer variable names, package names, method names, package and namespace prefixes, etc. You end up with some pretty long, yet very simple, lines. So an 8-spaces wide gap is too wide. Many modern editors, then, default to not using tab characters and indent, unless you specify otherwise, with 4 space characters. Indentation is usually a matter of appearance in many languages. In others, however, it’s very important. That’s the case of Python, which uses whitespace as a form of identifying blocks of code. This debate is more critical for those languages.

Proponents of using spaces to indent always mention that if you indent your code with spaces, it will display exactly as you view it no matter which editor you’re using. If, on top of that, you set the indentation width to 4 spaces as is the default in many editors, your chances of creating a conflict in the indentation style are smaller, so it’s a friendly way of indenting code, and a de-facto standard. On top of that, they will tell you to avoid using the tab character at all when working with Python, and make your editor replace everything with spaces always. This way you won’t be able to create invisible syntax errors by mistake. You can extend this practice to any other language, for convenience.

Proponents of using tabs will argue that using tabs is more flexible, because most if not all mainstream editors let you indent with tab characters and adjust the width of the displayed gap. So if Alice likes a 4-spaces wide gap, Bob likes 8-spaces wide gaps and Charlie likes 2-spaces wide gaps, they can all indent their code using tabs and adjust their editor settings. Code written by any of them will display in the preferred style of any other when they work on it. So, yes, those are not the default settings in many editors, but they’ll argue that this method is more friendly in the long run. Furthermore, they’ll tell you to interpret the tab character as a semantical mark of “deeper indentation level”. In the same way you can create a webpage specifying which blocks of contents you have and then use CSS to define how those blocks are to be represented, the tab character acts as a semantic marker whose appearance can be tuned in the editor settings.

Both sides are right in what they say, so that’s why it all degenerates into flames. You will have to choose one side yourself. For the record, I choose tab characters, as in my opinion the reasons on that side are stronger. Vim lets you choose the tab size (:set ts=[your preferred width]). I don’t know about Emacs but it would be a severe failure in its customizability if it didn’t let you. Kwrite lets you adjust the tab size too, and with it Kate and KDevelop. Even Dev-Cpp for Windows lets you indent with tabs and tune the tab width. I edit code with Vim usually, and avoid using spaces for indentation. It’s worth mentioning, though, that spaces are the preferred official way of indenting Python code and this is also reflected in many code style guides from different sources and entities.

2007-08-05

SlackRoll is ready

Filed under: Programming,Software — rg3 @ 19:44

It’s been a couple of months since I initially published the first version of SlackRoll, my particular upgrade manager for Slackware. I have announced it in a couple of main sites like Slashdot and the LinuxQuestions.org Slackware forums. The program hasn’t really taken off in the number of users, but I’m glad about the result in any case. It’s about to be tagged stable in both SourceForge.net and freshmeat.net. I didn’t have many chances of using it at its full potential, but I’m sure Patrick Volkerding will start making serious changes to the rolling tree soon now that Slackware 12.0 is out, and people will have a real oportunity of realizing how much time SlackRoll can save you.

Like I said in my previous post about SlackRoll, I started the project because I didn’t like the other available upgrade managers and wanted a faster and more bandwidth friendly upgrade manager, one that could save me more time, and I really did what I wanted. SlackRoll lets me read the ChangeLog without paying attention to the minor entries, the ones that announce that a package has been added or removed or upgraded, and focus on entries with more detailed comments. It knows about almost every corner case and notifies you of any important event, be it glibc upgrades, normal upgrades, new packages, removed packages, custom packages that get an official version or customized packages that are removed.

There have been many changes since version 1 to the now available version 14. Two important changes stand above others. The first one, a security fix in the GnuPG exit status treatment. I don’t know what I was thinking when I coded the initial version, but I screwed up and introduced a nasty bug that was fixed around version 8, if I recall correctly. I also changed the number and meaning of some package states. My initial design, that one I was so proud of, didn’t last long when I realized I could save time and detect more corner cases by introducing some changes. First off, the “outdated” state was initially calculated on the fly, when the user requested the upgrade or list-upgrades operations, for example. I realized I could save a lot of computing time by making outdated a state on its own and calculate it once. Second, the custom state was replaced by two different states in order to detect a couple more corner cases, which are the foreign state and the frozen state. Apart from that, there have been many feature enhancements, speed improvements and general code cleanups. For example, now the program caches the list of local packages and remote packages, supports having more than one local version of a package, implements several interesting search functions, orphan file detection and broken symlinks detection, among other changes. They are too many to be listed here, but SlackRoll is now my swiss army knife of Slackware package management, and it works faster and better than ever.

I would also like to encourage people to do things The Right Way. Remember to read the ChangeLog, subscribe to the slackware-security mailing list and give preference to SlackBuild scripts over third party packages, and avoid LinuxPackages.net if possible. Sites like SlackBuilds.org are a good resource if you want to introduce foreign packages in your system (using SlackRoll terminology ;).

Are you a Slackware user and haven’t tried SlackRoll? Don’t hurry to try it. SlackRoll is here to stay. :D

Blog at WordPress.com.