Je Hais Le Printemps

There's a deep trend in the dev world that is pissing me off a bit, now: instead of providing a tutorial and usage documentation about a project or a library, the authors are just throwing away the source code of their programme to their potential users. There are comments, yes. But it's just source code.

Yay, it's trendy. But it just kills me.

The first time I've seen it, that was about CoffeeScript. Fortunately, it was not the only documentation source. But now, more and more projects have jumped on the bandwagon. Sometimes, you can have a glimpse of how you may try to use the lib, or the project ; more or less.

But what triggered my anger was this insanely long "tutorial" list for backbone JS. Yes, you can scroll as long as you want, the first actual tutorial only appears after 10 pages of full examples ; some of them are well-done, with interesting comments. You often have a link to the expected "Annotated Source" page, where you can read the code and comments, side by side.

This NOT the solution. I CAN'T learn anything by reading a complete fully-featured listing, with all its elements, models, views, interfaces, etc. For at least one good reason, it's FINISHED. It's over, it's done, achieved, totally. It's DEAD to me.

I've once used Cooking as a metaphor for programming : what you're giving to me with your annotated source is dead beef, industrially-manufactured fast-bad-food dish. I'm reading the label with the ingredients, I know them all, but I have no idea on how you did to cook them, in what order, how did you mix them up and when?

What can I do with it if I didn't do anything BY MYSELF? What can I learn if I didn't follow the receipe STEP BY STEP, if I didn't experiment, tested (yes, "taste" and "test" share the same etymology), if I didn't adapt the dish to my tastes?

Reading a source code from the first to the last line is often, if not always, nonsense. You'll need to take it from the last line, that may contain a "main()" function, the one that calls the other modules. But at the top of your code, you have imported other libraries... Source code may look ordered, but it rarely is. At least, not chronologically.

What if I don't like one of your ingredient? Or if I don't have it? That's fine! I can replace it with something else. I often do that in step-by-step tutorials, replace a "employee / department" management example with a "beer bottle / category" utility, while following the steps. We do that all the time - except for pure algorithms, any ingredient may be replaced by whatever I want / need.

In a "real" tutorial, you see the dish being composed, one step at a time. It grows, it cooks gently. You see one module being used after the other, and the gears start turning with each other. And sometimes, you're using a method at the beginning, and then another one at the end : THE TRUE ONE, the one that is more lightweight, that's using a handy shortcut, the highest level of your API. You'll remember it all your life.

We have the chance to do, redo, again and again, practice a thousand times using different ways. Some people even perform code kata where you must acomplish a task, over and over, and over again, the same task, until it's perfectly done.

Annotated source code can be useful for people who want to dig into the lower-level engine, the ones interested by the guts of your library or application. But it is not and will never be a "primary" learning tool. It's some bone to chew for "advanced" users.

Please, next time you'll want to document your project, please provide a true documentation, a real proper "Usage" doc. And if you really think it's useful, add it your annotated source. But do not call it a "tutorial".

Otherwise, I may kill a sparrow.

Thirty-eight

Étienne Michel Patrick Marie Bord was born on June, 7th 2012, at 1:07am.

Comments are closed on this post. Those who want to drop a few words know how to.

A certain species of website exist for a while, now. In my opinion, it deserved a better treatment understanding and knowledge. Or better: a catalog. These websites are often funny, sometimes useful or enlightening. They usually show a great creativity and cleverness.

These websites are usually the anwser to a deep question. And hopefully, they do answer the crucial questions with a single word, like: "Yes". Or "No".

I've nicknamed these websites "monomessages", and I used to collect them in a "bookmarks.txt" file that I'm keeping in my Dropbox and I'm updating when I'm stumbling upon one of these gems of shortness and intelligence.

I've had this idea for a while, and now I'm diving into it: I've opened a blog talking about these "One Message Websites". The very first website is about to be published on december, 1st 2009, and I intend to keep on regulary blog about them.

I've got some interesting material, and thus a few weeks (months?) of all-prepared websites to show to the public. But the Internet is wide and I may have missed some of them. You may help contribute by sending an email (in English or French) to:

missing _hat_ onemessagewebsites *doth* org

You may want to follow the "One Message Websites" twitter account, too.

Rainbow over Wolverhampton, this afternoon.

Picture published under a Creative Commons license: BY-SA)

Fruit found in Bayonne (south-western France)

What is is? Is it edible?

The breaking news of the week-end popped in on every screen : the next Lugradio Live will happen on the 24th of october, in Wolverhampton, more precisely at the Newhampton Arts Centre. Two things I've noticed:

• I don't know the venue it will be the first time the LRL will occur in this "Art Centre".
• the LRL will only be one-day long (that would let me plenty of time to visit the highlights of Wolverhampton... erm, maybe not)

I can say I was a bit afraid that the announcement would be a bit too late (getting a cheap ticket can be challenging), and I feared that, because the podcast was stopped, and with all the things that can happen in life, they would give up with this event organisation.

If you are interested in this event like-no-other, you can follow its twitter account or on identica.

As far as I can tell, I'll do anything to be there. Now I'm afraid I'll really have to work on "something" to perform at this Live event.

Raphaëlle Maylis Odile Marie Bord was born on march, 22nd 2009 at 17h25, in Bayonne.

Comments are closed on this post. Those who want to drop a few words know how to.

PyRoom 0.4 is approaching, bringing a lot of new features, making it a first-class release. One of the key point is that the textbox has been revamped, not anymore depending on gtksourceview, which will help us a lot being cross-platform.
The efforts of the Dev Team show much progress on the Windows port. It would be very nice if someone using Mac OSX could test the latest trunk checkout and help us know if it's usable on their OS. It would be so nice to have kilt-wearing maniacs (just kidding) using PyRoom instead of Writeroom.

It may be interesting to note that translatable strings are available, and anyone wanting to help translating PyRoom in any language is welcome. The good thing is, with Rosetta, you just need a web browser to play.

Quick reminder: any bug report will be on Launchpad, thanks.

Oh ! speaking about Launchpad, I've been very suprised to see a text I've sent some time ago to Matthew Revell land on Launchpad blog. He justed asked me why I choosed Launchpad to host PyRoom. I didn't think it would make an article...

Last, but not least, if you search in the latest FOSDEM video archive, you may find a video with a beardy french geek, speaking english with an outrageous british accent trying to explain how PyRoom is an interesting tool, despite its being featureless.

The sound is terrible. I'm sorry, t'is not my fault.

Although I was a bit disappointed by the general schedule of FOSDEM 2009 - but that is just my own opinion - regarding the topics I'm interested in vs. the given talks... every bit of the talk I gave about PyRoom is now available via the dedicated page.

The usual Lugradio Live crowd may be confused: it's a serious talk about a serious topic, since it's the very first time I'm giving this kind of talk in english.

Now we'll have to wait for the videos, soon-to-be-released.

Well... I think everything goes well, now. Since my talk about PyRoom at FOSDEM proposal has been accepted, and now scheduled.

Thus, my timeslot has been set to Sunday, the 8th of February, at 15:00. And even if my talk is about 80% ready, I still already feel nervous... Meet me there!

Too bad tiax can't make it to FOSDEM, I think PyRoom wouldn't be at this point without him. We'll drink a few beers thinking about you, mate.

It's a project that's no much worth, but might be a bit handy. In fact, I haven't even been clever enough to have the idea myself: it was Jeff Winkler who gave it a kick at the first place.

The issue

When you are using TDD methodology, here is how a coding session works. You add a test case to your tests, you launch them, they fail - or not, but usually, they must fail - and you start coding, you look for a solution, and then you run your tests until the test pass. Rince, repeat, until it's ok.
The boring bit is sometimes the manual switch from your editor to a system shell to run your tests, and watch the result, and back on your editor again, and again, yadayada...

Start of a solution

The nosy.py script by Jeff Winkler is quite a start. It's a program that builds a list of files within a project (a directory), and as soon as one of them is modified, it runs "nosetests" . You have to know that nosetests is a python tool that runs every test it finds in a Python project. Very very very handy...

The glitch

Someone (like me) who uses Django has to run a different program. Because running nosetests may not work properly. In Django, you run:

$ python manage.py test

My solution

Then I tried to build a more flexible nosy.py and allow more than one test program, as the user wants it.

So, this "test daemon" code bit is available via github. Once git is installed, you may grab it like:

$ git clone git@github.com:brunobord/tdaemon.git

The important file is tdaemon.py . You may want to make it executable and accessible from your path and run it that way (for example):

$ python /path/o/tdaemon.py /path/to/project/

By default, tdaemon uses nosetests, but you can use py.test or the django test tool. I didn't try it, but I'm almost sure you can use any other test tool, once it would be implemented in the script.

Of course, I'm keeping an open eye on any kind of improvement you may want to bring in it, or report any bug, etc. This is just a bit of code, far from being perfect, but it works (for me, at least).

(as we are talking about that, I'm trying to use git a bit more often and I hope this project may help me in mastering this DCVS - and github services, too. My brain is more easy with the bazaar logic, and I can't quite get my head around git at the moment)

Enjoy!

[via NiKo]

I should pattent the CDD methodology: Chaos Driven Development

A quick search doesn't show anything valuable...

Hereby I'd propose these guidelines for anyone who wants to dive into CDD method:

• Specifications should be written by throwing small rubber balls on a keyboard linked to a text editor. You may want to continuously repeat this for a week or so. Then you can give the result to a blind person - I'm pretty sure disabled people can enjoy CDD too.
• These specs may now be cut in small tasks by the "project manager" - or, as we name him in CDD, the "M.O.R.O.N.", i.e. Manager Of Relationships Out of Nowhere)
• Each task may be assigned a priority. This is being randomly chosen by an innocent hand, or more precisely the innocent pad of a Schrödinger cat. If the cas dies, the task priority is low. If he's alive, the task is critical.
• The CDD now enter the scene. They must work as pentanomes (group of 5 people): the first one types on the vowels on the keyboard, the second one hits the consonants, the third one takes care of non-alphabetical characters (spaces, commas, digits, etc), the fourth dictates the code to the others, while the last one is been given the task to jump on the keyboard from time to time to add entropy to the system.
• for each task, you must assign, five pentanomes (yeah, the number 5 is cult in CDD, it's so "dada"). These groups are writing code at the same time, on the same working copy, confusing each other's code.
• No need to say, test-driven methodologies are banned. No-one should never ever test the programs. Especially the developers or the customer.
• The software produced may now be shipped via email, to a randomly-generated-email-address generated by a cosmic-background-powered-generator.

For more efficient results, you can move as close as possible from the LHC.

After a few evenings of work I finally managed to hack on a minimal code to publish Beer Over IP using a tiny Django application (0.96).

To get the full power of this awesome application (you know you want one in your living-room, right?) just quickly browse the list of available beers. Yes, I know... At the moment, it's a short list... But thanks to the "user-generated-content" principle, you can help providing more items via our Launchpad bug interface. Please send us:

• the name of the beer,
• a picture or a link to the picture, with the absolute requirement: it must be Free (Creative Commons, license, for example),
• appropriate credits,

Yes, it's your turn. With your help, your favorite poison will soon be available to anyone via the Internet Protocol.

The source code powering this website is distributed under a dual license... You may redistribute it using the terms of the WTFPL or the BEERWARE license. The first one allows you to do what the fuck you want with this code, while the other ones offers you to do what you want with this code, and if we meet in real life, you may buy me a beer.

(note: for this application, I didn't follow the principles I told about in my previous post. I know. But this is a pet project, don't make me think that this project deserves a multiple team organisation)

As it has been announced on our Launchpad Project page and as Florian "tiax" Heinle sent a reminder to us all, PyRoom 0.3.1 has been released, and is ready to be translated... So far, a few languages have been quickly done via Rosetta, but anyone knowing English and another tongue may proceed and help PyRoom being available in every available language on Earth (and beyond?)

Let me inform you that, after a few geeky-kung-fu actions, you may instal lPyRoom in Ubuntu using our officiel PPA repository.

Typing

sudo apt-get install pyroom

Oh yeah.