Reading docmentation

Reading documentation is an art, and can be very enjoyable if it is well written.

As a software developer, one of my aims is to write documentation that people should want to read, while designing systems that work well without having to read the documentation. Seemingly opposite goals.

I have a habit of reading documentations. And when I say reading, I mean thoroughly.

One of my earliest memories with computers was me failing to jump between buildings in a spiderman game, giving up, and spending time reading windows help. I have read almost every single page in windows help for XP, back then.

It was the beginning of a habit. When I started programming in python, which was after entering college, I read python 2.7 documentation. Every single line from every single page. All the functions in all builtin modules, changelogs, what’s new, guides, the whole deal. It changed me. I would write programs very differently.

The habit persisted. Pretty much any technical document I read, I read it in entirety. A friend commented that I was incapable of skimming things. He did not imply it was necessarily a bad thing.

Among other documentations I’ve read are a few notable ones – Docker, Erlang, Bash, git. Did you know Bash can do tcp/udp communications by writing to special psuedo files, and : is a valid command, bash’s own noop, handy for commenting blocks of code?

Elasticsearch joins this list tomorrow. I’m close to completing a new set of docs – something larger than a hundred pages – after long. Feels good.

Advertisements

Recursion in livescript

I have been looking at JavaScript, and languages that compile to JS. Coffeescript was my first love in this domain, and I have very recently transitioned to LiveScript, just a few months ago.

Until now, I was not faced with a problem for which recursion is the most natural solution. A couple of days go, when I was writing this program to test for a palindromic number, a recursive implementation seemed the most sensible approach. LiveScript being my new found love, I fired up vim, and… blank.

I tried searching on google, but it turned up nothing useful. I spent almost half an hour reading livescript and prelude, to find these two solutions. Turns out that you can use the keyword function to create named functions, which get hoisted as usual with javascript.

function fib x
   if x<0 then throw new Error
   if x<3 then x
   else fib(x-1)+fib(x-2)

Or, you can use the fix function from prelude to do anonymous recursion. This is the first time I saw the beautiful Y combinator being used this way. And I had to read my old notes on Y combinators and Javascript call and apply to understand the magic of what is happening.

require! 'prelude-ls'.fix

fib = fix (fib) ->
   (x) ->
       if x < 0 throw new Error
       if x < 3 then x
       else fib(x-1) + fib(x-2)

Looks similar? Nope. Here, fix takes a function that returns a function as an argument, and returns a function that is the inner function, with the outer argument referring to the inner function itself. Did that make any sense? 😀

The beauty of this approach is that the function fib doesn’t get hoisted, it is just an ordinary variable assignment, not a named function, and we just did anonymous recursion!

Don’t know if the sound of it excites you, but I sure am excited. Recursion in an anonymous function? Isn’t that cool?

Actually, looks like one of the common applications of Y combinator is to do anonymous recursion, but I didn’t think of it earlier.

Because we did the same

Did you ever look at something that made you pause a moment and think “what the hell was that?” If your answer is no, please stop reading here. You do not belong in my target audience.

Something may elicit such a response in two cases. Either it is extremely good or extremely bad, good and bad being defined subjectively. Mediocrity doesn’t stand out from the crowd. It is the extremes that demand attention. It is thus extremes that I am interested in.

This is my personal rant. I was asked to do a shitty job, and I can not escape it because it is a part of a core course, which needs to be completed for me to obtain my degree, and I need my degree. Not really. People think I need a degree, and people think it reflects my competence, which I assure you it can not. Anyone who thinks GPA and certifications mean anything more than a belief in the system, is delusive. Back to the point. When I requested that I be allowed to do the same job in an alternate way, it was denied. I will now detail the incident and my thoughts on it. Feel free to abandon this post and move on if that doesn’t sound exciting.

What happened?

I am undertaking a course titled ‘Software Lab’, which requires me to work on one assignment per week. This week, the problem statement is to make a Ubuntu app that displays weather information. So far so good. I am required to learn Tcl/Tk, and no, GTK/QT are not allowed. I need to version control with cvs, and no, git/hg are not allowed. I need to use a database to store last 30 days’ weather information, and it needs to be mysql. It is actually laughable to require RDBMS for such trivial task, where a csv sheet does the job.

Why am I angry with this?

A new set of tools every week demands my time. I have to postpone a lot of my tasks to make space for learning them. (Actually until this week, I was teaching people, since I was already well versed with the tools.) When I invest time, I expect them to be of use.

  • I will not program ever in TCL/Tk after this assignment. Because I know GTK and QT, and they are far superior for creating a GUI. Also I am not a Tcl fan boy who loves the weakly typed dynamic language with everything being a string.
  • I will never use cvs again, because I work primarily with git, it does everything I need, and hg can handle those few exotic cases where git doesn’t quite fit in. Cvs sucks.

To most of my classmates, a 2 credit course demanding entire week, every week is unfair, and has severe effects on other courses. For me, having to work with outdated tools is the bigger problem. If you are a developer, you should probably be able to understand why.

I requested the teaching assistant (TA) and he refused any alternatives. The professor-in-charge says if the TA is familiar with something, it can be used. And the TAs draw a blank on hearing RDBMS, DVCS, git, mercurial, Gtk, QT, or pretty much anything under the sun. I will label them illiterate in programming. When one of my friends commented the alternatives are better, so why can’t they be used, I hear the beautiful reply that prompted this post.

We did this course this way. You have to do the same.

Wait, let’s back up. When was the last time you saw a developer choosing Tk or cvs out of his/her own will, given the alternatives? Probably a decade has passed since such an event happened. And so, atleast since a decade, while the real technology has progressed much, the academic machinery has preserved its notion of what is to be taught, unscathed, to the point where it diverged from what is usable in reality to a horrible extent.

Thanks for reading this far.

This entire article can be distilled into this. Classrooms and labs must do a reality check of what is relevant, and must incorporate those changes into the curriculum, and this must be a continuous process. Teaching assistants must be trained well. And get some literate folks in there, please!

You may suggest that I explain the situation to the professor. I was hoping I could do that, but today evening while I was in a meeting with some other professor, the entire situation worsened, and I do not think I would be able to convey my message now. I am still unaware of the discussion that happened between my friends and the professor, but it must have hinged on the course demanding too much of their time, as it was decided that the relevant links will be provided a week early, and the actual coding has to be done in the four hours allotted to the lab. It definitely wasn’t the right approach.

Screw everyone, because that means the lab starts at 1 and I can not have lunch that day. The problem remains unsolved. And screw everyone again, because the information is being as abstract as it can get. “The next week’s work will require Object Oriented Programming in C++/Java.” Along with links to C++/Java tutorials probably grabbed off the first page on Google. Essentially I see zero profit and a net loss.

Last week required us to do a multi threaded implementation of matching two strings. In shell and C. If the aim is to frustrate people like me, job well done. But if it is something that was designed to teach multi threading, give a problem statement that makes sense. Multi threaded search does not make any sense when the input sizes are small, as in less than 10 characters. It may make sense in the case of a short string being searched inside a very long one. Evaluation plays an important role. If I see evaluation that does not reward work, that doesn’t even make sense because essentially the TAs are illiterate, I feel justified in losing interest in any learning opportunity that the course may provide. I am a normal human being ape, and I am affected by these.

There is a reason I am beginning to consider any parent who wants to send their kid to school, mentally retarded. More on that later. If you are offended by any of the above statements, you are welcome. I don’t give a shit.

Maybe you are…

Maybe you are the kind of person who is afraid of failure so you give up at the first sign of difficulty. Maybe you never learned self-discipline so you can’t do anything that’s “boring”. Maybe you were told that you are “gifted” so you never attempt anything that might make you seem stupid or not a prodigy. Maybe you are competitive and unfairly compare yourself to someone like me who’s been programming for 20+ years.

Continue Reading