Open source writing using Git

Of late I have noticed a trend – writers, especially technical writers, are embracing the software development process and incorporating it into their writing process. There’s a great podcast about this on Herding Code where some technical writers talk about this trend.

Writers are embracing the agile philosophy of software development, one of the core tenets of this is to publish often and get feedback so you can improve/adjust. Authors are posting the content for their book projects online to get feedback – to the extent that publishers like Manning and O’Reilly offer programs that let people access to the book content as soon as the author creates it, for a discounted amount. The pioneers of this practice were the Pragmatic Programmers who offer “beta” versions of their books to customers at discounted prices. The idea behind this of course is that it lets authors get valuable feedback as to what is important, what to focus on. It also provides, authors with an incentive to keep from procrastinating about their writing.

Another major aspect of this trend is the embrace of source control in the writing process. I think this is a great development, and it makes a lot of sense if you think about it.  The book writing process, like software development, is subject to a lot of chopping and changing as the book evolves. Also writing collaboratively on something is I imagine similar to writing code in a team and probably have the same issues –  one needs ways for multiple people to be able to work on the same document without worrying if they are overwriting someone else’s hard work. Finally, a version control provides you with a fine-grained backup that allows you to rewind and replay the evolution of the book, which should be invaluable during the editing process. If there is a conflict somewhere, version control also offers tools to detect and fix it in a safe manner.

Some authors have posted their content on Github, which I think is an awesome idea.    Leveraging, the capabilities of a version control, especially a powerful and distributed one like Git and Github, is well suited for writing projects. Authors can leverage the tools  and capabilities of Github  –

• On Github, feedback can easily be provided in the form of  commit notes, line notes, issues – heck you can even fork the project make the corrections and submit a pull request back to the author.
• You can use Git as a fine grained distributed backup for your writing project that allows you to rollback specific portions of you project independently.
• You can use the social features of Github to collaborate on the project and even drum up interest by distributing the link online.
• You can maintain your code samples and other resources separately from your content and correct and upgrade them as needed. This can be very useful if the book is about specific technical frameworks that get upgraded after the book is completed and published.
• Github even has a basic editor so you can work on your project online

While browsing through Github for examples of books that use Github as a version control system for writers – I came across this tool which is  in my mind a good first step, but I think there is a lot more that we can do to improve this experience. There are a whole lot of tools being built around this concept which is quite encouraging.

Writing and programming, have a lot in common. Both involve text, both are creative activities and both are ways to express ideas (one to a machine and the other to an audience) . There is scope for a lot of cross pollination of ideas between these fields. I think, currently the main challenge is a lack of knowledge and a fear of the technical nature of a tool like Git.

Related links

• Git Scribe
• On writing technical books
• Arcturo ebooks on Github
• Mordern Perl book on Github
• Backbone fundamentals on Github
• Node Beginner on Github

Advertisement

A Ruby on Rails glossary.

So it’s been about a year since I started working on the Ruby language in the context of the Rails framework. It’s been awesome,  the combination of Ruby’s developer friendly language style and the incredible productivity of the Rails framework makes this a killer framework for web applications. Building the basic code is simply a matter of typing in some commands that generate all the scaffolding of code needed for a basic website. The rest is usually a matter of tweaking and adding to the generated scaffold.

Image by dullhunk via Flickr

Like every web technology the Ruby on Rails framework has its own set of idioms, that one needs to get familiar with and since I am new to Ruby, for me this includes some Ruby idioms as well. I saw a post today that lists a glossary of Rails terms and I thought I’d do my own. So here goes –

1. Application Servers – Thin, Mongrel, Passenger, Unicorn, Pow – These are application servers that run the Ruby web application and respond to the requests. They are generally integrated with a web-server like Apache or Nginx, though Mongrel is technically capable of running on its own as a web-server (though since it is not multi-threaded this configuration is not useful for anything except for very light loads or on a development machine).
2. Active Record – Active record is the ORM tool used in the Rails framework to abstract the database handling. It is an implementation of the active record architectural pattern described by Martin Fowler thus – “An object that wraps a row in a database table or view, encapsulates the database access, and adds domain logic on that data.” The Active Record code is available as a separate gem that is downloaded as a dependency to Rails.
3. Active Resource – A simple way to think of active resource is that it’s like active record but for REST based web-services. Active record provides a wrapper around REST actions providing a transparent proxy between a business entity and REST based web-services.
4. Active Support – This is a set of utility classes and standard library extensions that are useful in Rails application development. It includes classes for dealing with caching, dates, time zones, text, etc. Like active record and active resource, active support is available as a separate gem that is installed as a dependency of the Rails gem.
5. Bundler – Bundler manages the gem dependencies of a ruby application in a repeatable way across multiple machines. It automatically looks for and installs / updates all the gems needed by the application when it is deployed on a machine. It can do this is a repeatable way across multiple machines and deployments.
6. Capistrano – Capistrano is a tool for executing command on groups of servers over SSH. It is used mainly in deploying web applications and is capable recognizing different types of server environment (like staging and production, etc).
7. Capybara – This is an advanced version of the Webrat tool. It lets you do acceptance testing of applications using various drivers (Selenium and Rack are built-in) by simulating a real user hitting your web application.
8. CoffeeScript – Coffee-script is a little language that compiles into java-script. It has rapidly become very popular and has been included in Rails 3.1 as the default method of writing JavaScript code in a Rails application. I am personally a bit on the fence here but I like its terse syntax.
9. Cucumber – Cucumber lets software development teams describe how software should behave in plain text. The text is written in a business-readable DSL and serves as documentation, automated tests and development-aid – all rolled into one format. Cucumber along with RSpec are main tools used for the BDD methodology favored in many Rails projects.
10. DSL(Domain Specific Language) – A domain-specific language is a language dedicated to a particular domain or the representation of a particular problem or solution. DSL’s are more common than you think, some good examples in the Ruby being – Cucumber, Rake, Haml etc.
11. ERB (Embedded Ruby) – ERB is a simple and powerful templating system for Ruby. It is part of the Ruby core and it allows one to place ruby within other files (any text document).
12. FactoryGirl – This is a gem that can be used for creating object factories in an automated fashion. This is useful in testing or even for populating an application when deployed
13. Gem – At its most basic form, a Ruby gem is a package. It has the necessary files and information for being installed on the system. There is an online repository for Ruby gems at http://rubygems.org/ For me this is the biggest find and literally the “hidden gem” of my Ruby learning experience has been – Ruby Gems.  It’s like having an app-store for your development needs, where most of the best gems are freely available to you!  The number of awesome, useful gems actually available to ruby developers means that we have a huge advantage over other frameworks. A testament to the power of Ruby gems has been that Microsoft has started its own package management library – Nuget which, seems to be simply a straight lift of the Ruby Gems concept, except of course they have incorporated it into the Visual Studio as an extension. Nuget was released by the same team that created the Microsoft version of Rails – ASP.Net MVC so you can see the Rails influence…
14. Gherkin – Gherkin is a DSL  that emerged from the Cucumber project. It was designed to succinctly describe behavior in a form that can be acted upon by a tool like Cucumber. It is described as business readable DSL and can be used in any project that has need of such a tool. The lexer and parser for the language has been create and the library is available in several frameworks including Ruby, JVM, Javascript (Node.js) and as a .NET dll.
15. Git – Git is a free and open source, distributed version control system. It was written by Linus Torvalds to replace the old source control system for Linux and has become one of the tools of choice for a lot of Ruby projects. Git is typically used along with Github which is an online source control repository that leverages Git.
16. Haml – Haml is an HTML abstraction language. Haml functions as a replacement for inline page templating systems such as PHP, ASP, and ERB, the templating language used in most Ruby on Rails applications.
17. Heroku – Heroku is a cloud based platform as a service (PaaS) which was one of the first to have Ruby and Rails support. One could build a Rails application and directly deploy it on Heroku without having to set up a web-server. The platform has evolved to support multiple languages including Java, Scala, Node.js, Clojure and Python.
18. jQuery – jQuery has become the JavaScript framework of choice for web developers everywhere. It is a fast, framework that leverages CSS style selectors to allow developers to traverse, animate and handle events in the HTML DOM while abstracting browser specific quirks as far as possible. It has become so popular that it displaces Prototype as the default JavaScript framework used in Rails 3 applications.
19. Memcached – A distributed open source caching system, memcached is an in-memory key-value store for small chunks of arbitrary data (strings, objects) from results of database calls, API calls, or page rendering. It is a generic store and can be used in any situation where caching is needed and is available in multiple languages and technologies. It is used in a lot of Rails applications even though today, other object stores like Redis are getting popular.
20. Merb – Like Ruby on Rails, Merb is an MVC framework. But, it a lighter and more barebones version. I haven’t used Merb – I’d love it if someone could give a more apt description of what Merb is and how it compares to Rails and Sinatra.
21. Open classes / Monkey Patching – Open classes is a feature of the Ruby language where you can simply open and add methods to existing classes. Active support library uses this feature to add a lot of its helper functions on the Ruby core classes like string. A popular name for this particular practice is “Monkey Patching”.
22. Paperclip – Its a complete (and easy) file attachment library for active record. It provides validation features based on the properties of the file like size, type, etc. The files themselves are saved in the filesystem. It has some basic image manipulation features as well, like creating thumbnails etc. There is a dependency on the ImageMagick library (an awesome image manipulation library) in order to use Paperclip.
23. Prototype – Prototype is a JavaScript Framework that aims to ease development of dynamic web applications. It was originally the default JavaScript framework bundled with Rails.
24. Rack –  Rack is a gem that provides a simple interface between a web-server and the Ruby web framework. Rack is used in various Ruby web frameworks, like Rails, Sinatra and Merb.
25. Rake – Rake is the ruby version of make but much more developer friendly. It provides capabilities that are similar to make but it uses the Ruby syntax instead of XML files or makefile syntax to define tasks.
26. REST(Representational State Transfer) – REST is a set of principles that define how Web standards, such as HTTP and URIs, are supposed to be used. Well, actually REST as a concept is more abstract than that – its architectural style that can be applied to distributed systems. REST in the context of Rails, mainly is used to refer to the way Rails exploits REST concepts in the way that Rails web applications are structured.
27. RJS(Ruby JavaScript) – It is a ruby helper used to generate JavaScript that are used to decorate HTML pages. It is used mainly in AJAX calls, and in situations where you wanted to conditionally emit JavaScript. The general opinion though was that it sucked and was avoided in favor of the unobtrusive style of jQuery.
28. Routing – Routing is the aspect of the Rails web application that deals with the translation of a URL request to a specific action in the application. In Rails, it is the job of the router to recognize URLs and dispatch them to a controller’s action. It can also generate paths and URLs, avoiding the need for hardcoded strings in your views.
29. RSpec – RSpec is a Behaviour-Driven Development tool for Ruby programmers. RSpec helps you do the TDD part of that equation, focusing on the documentation and design aspects of TDD. Like Cucumber RSpec uses a DSL to simplify design and implementation tests.
30. Ruby Debug – Just like it says on the tin – it is a debugger for ruby applications. Like the other tools it is gem that can be installed and can run your ruby application in debug mode.
31. RVM(Ruby Version Manager) – This is an awesome tool from Wayne Seguin that is used to install, manage and work with multiple versions of the Ruby programming language on your machine. It even allows you to segregate your gems so you could work with multiple versions of the same gem for different applications.
32. SASS & SCSS – These are CSS abstraction languages (I believe SCSS is a reference to the version that supports CSS3). They are compiled down to CSS. They allow you use variables, modules and include other files. I am not very familiar with them and would welcome more information from readers.
33. Sinatra – From the website – “Sinatra is a DSL for quickly creating web applications in Ruby with minimal effort.” Like Merb, Sinatra is a minimalist web framework. Again, like Merb, I haven’t used Sinatra at all and would welcome some comments to flesh out this entry.
34. Test::Unit – This is the default testing library available with Ruby. It is from the xUnit family of testing frameworks and is a part of the core Ruby libraries. It is mostly not used in favor of more powerful BDD style tools like RSpec.
35. UJS(Unobtrusive Javascript)– “Unobtrusive JavaScript” is a general approach to the use of JavaScript in web pages. The general principles of this approach includes –
    1. Separation of behavior from the markup – The HTML in a document is meant to describe the structure of the document and should not contain programmatic elements in it. This is similar to the principle of separation of the structure from the presentation of the document when talking about the separation of CSS and HTML.
    2. Should not pollute the global namespace – UJS code should add as little as possible to the global object or global namespace of the environment in which it runs.
    3. Degrade gracefully – If the browser rendering the document does not have the capability needed the code should be able to degrade gracefully without breaking the rest of the application.
36. Vim – IMO Vim, the text editor that just celebrated its 20th anniversary in 2011 has experienced a resurgence of sorts with the rise of Ruby and Rails. In fact there is a large number of Vim plugins that have been created to make developers even more productive and happy on this text editor. Indeed after Textmate (the other favored tool for Rails developers) I think Vim has the biggest following among Rails developers and the fact that its available even on Linux and Windows only makes it cooler…
37. Web Servers – Apache, nginx, Lighthttpd , Thin – In the Rails world web servers options include Apache, nginx and lighty(lighthttpd) of which Apache is by far the most popular. I have included Thin in this list as well since it includes both a web-server and an application server. With advent of PaaS providers like Heroku, this particular aspect of web application development is becoming abstracted out, just as the database is getting abstracted on the other end.
38. Webrat – This is a headless browser that is used in web application testing. It lets you run in browser test without the associated overhead of actually instantiating a browser. This does not execute any JavaScript but is great for doing tests of simple websites without much JS interactions.
39. Will_Paginate – This is the most popular pagination library out there for Ruby on Rails. It alos supports other Ruby web frameworks like Sinatra and Merb. This gem has a wide variety of formatting options and can accept an active record object or even a simple array. It is quite configurable and can be easily extended to do AJAX pagination as well.

So, that’s all the terms that I can think of so far, I’ll try to add to this as and when I come across more terms. Nowadays, web development is more than a single framework, even one like Rails.  I have found the Rails community is more open and embracing of different ideas and frameworks – even to the extent of moving away from Rails and using lightweight frameworks like Sinatra. IMO that makes this glossary all the more relevant and fun.

As I have mentioned in the article I don’t profess to be an expert about or have even used all the tools and technologies listed above. I would love to get your comments and suggestions on what could be added.

And last but not the least – I wish you all an awesome 2012 – may all your efforts bear fruit this year.

Update (Jan 12 – 2012) : Since there has been some interest in this post, I have added a few more entries and provide more information where I can – stay tuned :-)

How to read code – a primer

I like programming – it’s what I do and I am blessed in that I get to spend most of my waking hours developing software. Like a lot of programmers I obsess over how good my code is and how I can get better at it.

Over the years there have been reading a lot of articles and books on software development. There has been a lot of ink spent (both physical and virtual) on ways to improve your “programming foo” and become a super ninja programmer ! There are some common pearls in all this ink and one of them is the advice on reading code. This advice, is usually a one liner couched in the midst of a bunch of other recommendations and usually along the lines of – find some great open source software or any piece of software that you admire, open up the source code (or print it out) and read it. While, this is on the whole, great advice there are some problems with actually putting it in practice.  In this post I endeavor to give some practical suggestions on reading code, but first let us enumerate the problems.

• The usual impression conveyed (in the posts that advise one to read code) is that the dispenser of the advice is a programming guru who can literally sit back in their chair with a page of code and read it like a novel. Well, I am sure there are some superb programmers out there who enjoy looking at pages of cryptic English-like statements over a cup of coffee and can hold entire class hierarchies and architectures in their heads. This post is not meant for them – this post is for poor slobs like me who find staring at reams of code a boring, frustrating and ultimately pointless exercise. Of course, it can be argued that one can learn simply by reading a single class or even a function of a the entire project code, but, IMO, except for the most simple problems, most software is interdependent. It is often impossible to appreciate the design decisions and the rationale behind a particular function or class layout without knowing the rest of the system…
• The next problem is getting code to read (actually before that you need to be able to identify code worth reading – check out this post for details on that). There is a lot of great software out there – both open source and freely available and licensed or proprietary. There are huge open source directories like Sourceforge and Google Code, and huge pieces of software like Open Office and Linux. If you are working in a software development company, you can probably get access to the proprietary code in your source control repository. A third common avenue are the programs distributed along with books on software development  or as part of resources for  education( Minix being the canonical example). Indeed we are actually spoiled for choice and from this universe of software identifying the ones that are good candidates for our purpose is a hard but essential task.
• Another problem is the language in which the program is written – reading someone else’s code is tough enough as it is, adding the burden of familiarizing yourself with the quirks and syntax of a new language while doing this, is, IMO, a recipe for disaster and immense frustration . You need to find code written in a language that you are familiar with. This particular problem is not relevant if you are going through the code distributed as part of a book or as an educational resource, since you would have the book or your mentor to explain things and set out the context. If, despite this forewarning, you are planning to read code written in a different language than you are used to (without the benefit of having a book or a mentor) I would advise, that you at least learn enough of the language to create your own programs  in it (“Hello World” does not count :-)) .
• The bit about context brings me to the next problem – figuring out what the code is doing is a lot harder if you are not familiar with the software itself. For example, it is far more difficult to go through the Linux code and figure out the concept of runlevels if you don’t use Linux daily and see the Linux boot sequence. Using the software gives one a context with which to read the code – this context includes the common terminology used, the functionality and features of the software, even the quirks and bugs that you experience.

I have realized that for me ‘reading code’ does not really describe the activities that I undertake – a better phrase for what I do is ‘code comprehension’. It is quite difficult for me to sit back with a laptop screen (or a printout) full of code and simply read through it. I need a lot more than simply a piece of code – I like to be able to look at documentation, play with the software, step through the code and even write tests for it before I really appreciate it. This is a significant investment of my time and effort, so I have to be very picky about the software I want to “read” (comprehend).

• The first filter I place on the code directory, when looking for code  is the language filter – for me this means – C# or VB.NET or Python or Javascript(while I am familiar with C++, Ruby and F# as well I do not consider myself at a level where I can understand other people’s code in them). Next is to look for software that I have used – this allows me the a bit of a leg up since I know what the code is meant to do, cannot do and (if I am familiar enough) its limitations. Good candidates are open source software that you use in your day job (for eg. I use Cruise Control.NET, NANT and NUnit which are open source tools written in C#)
• I happen to work in a software product company (a Microsoft shop), so one of the candidates for my reading list is the code in my companies source repository. If you happen to work in a software company, you can look at other projects, and even older versions of the software you are working on. In addition to providing insight on code, you get a pretty good idea of what was tried before and since. There are a few caveats though –
  • First, if you don’t have direct access to other projects, you need to ask permission – some companies are very touchy about their “intellectual property”.
  • Second, the quality of the software may not be as high as you think, since, in general, proprietary code does not get the kind of scrutiny open source code does. Warning signs to look out for are a lack of regular code reviews – if the software is not code reviewed the odds are that it would not be of good quality.
  • Third (this point is inspired from feedback provided by my friend Praseed), if the code in your company is business software (HR, Finance, ERP, etc) there is a lot of business context that needs to be understood first. Also, since most of this code tends to be factored by business functionality, it generally seems less modular than utility code or APIs.
• Look for well documented projects (this applies to open source as well as proprietary code).  By this I mean, that the documentation should highlight the overall design, and rationale for the way the code is. Simply having auto-generated Java Doc type documents cannot be considered documentation :-). One useful avenue to explore is software created as educational resources (like Minix ). Since, the target is to teach through the software, they are usually quite clearly documented and have plenty of material explaining the design rationale behind the code.

So, you have identified the software and downloaded the source code and documentation, so let’s get down and start spelunking ;-)

• Go through the design documentation and try to get a feel for the way the code has been built. Good software projects follow certain architectural patterns – these dictate the code organization. Once you get a handle on this, understanding the code becomes a whole lot easier. If you can create a class diagram of the code you can get a good idea of the layout.
• The next thing to do is to compile it and run it. This can be straightforward or tough depending on the process followed in the project and it’s documentation.
• Now it’s time to fire up your favorite IDE and go exploring. A good place to start your code exploration  would be to try to trace a functionality of the project that you are familiar with. This would let you go through the various layers and sub-systems and get a handle on how they inter-connect. For example when I was exploring NUnit – I started by writing a test and looking at the code classes I needed to do that.
• Try and identify the design patterns used in the code. If you do not know what design patterns are, then you need to stop reading this post right now and read this book. Familiarize yourself with design patterns – they form a great way to recognize and understand the design of well written code. This makes it easier to keep it in your head while reading code. It also helps you identify nuances and customizations made by the programmers more easily.
• Try to write tests for the code to fully understand it – this is really useful way to understand the dependencies between different parts of the code. When you try to write a test for the code you first need to satisfy (mock) all its dependencies. Next you need to understand the possible entry points as well as the exit values for the code. This improves your understanding of the code and get you to the next level.
• Finally, try to refactor the code. In this step you have moved from simply understanding the code to becoming familiar enough to be able to modify it. As the sophistication of your refactoring increases so too does your understanding. At this point you can if needed contribute your own code to the project :-)

“Code Reading” IMO is more than just reading – it is a distinct set of activities that together help one understand code. It might seem more intimidating than simply “reading code” but it is well worth then effort IMO.

Happy “code reading” :-)

Update: I came across this post by Joel Spolsky where he quotes Seth Gordon as saying code reading “Is just like reading the Talmud”… Yup, code reading is definitely not easy.

Ganesha – the original lateral thinker

There is an ancient tale from Hindu mythology that illustrates lateral thinking (also known as –  “out of the box” thinking) that I would  like to share –

One day Lord Siva and His consort Parvati were sitting atop their abode on Mt. Kailash with their sons Ganesha and Karthikeyan when the sage Narada dropped by for a visit. Narada had with him a special mango of knowledge, to offer to Siva. After accepting the mango from Narada,  Siva and Parvati decided to have a contest between their sons.

Ganesha

Karthikeyan

The first one who circumnavigates the world three times would get to the mango of knowledge. Without further ado Karthikeyan  jumped on his peacock and started off. Ganesha on the other hand was busy eating his favorite ladoos and decided to finish them first. Karthikeyan had completed two rounds by the time Ganesha finally got ready to compete :-)

Ganesha simply approached Siva and Parvati and deliberately walked around them –  He circled them once, twice and three times and then claimed the mango.

When, Siva and Parvati asked him how he could claim the mango when he had not circled the world even once – Ganesha replied – “You both are my world”. Delighted by the answer Siva and Parvati gave Ganesha the mango, which he immediately gobbled up with relish.

Two of the important traits of good software developers are “enlightened laziness” and “Out of the box” thinking.  This tale is an example of both enlightened laziness and out of the box thinking – confronted by the immense task of circumnavigating the world – Ganesha – by simply thinking a little and restating the problem comprehensively defeated his brother Karthikeyan.

So, my eager friends – the ones who are chomping at the bit after the initial presentation of a project – eager to rush into coding it, please spend some time contemplating your problem.  Another, homily you might want to consider is –  “Think twice, code once” – You, might just save yourself a LOT of time and effort !! :-)

Learning Software Programming Takes Time

This comic created by the Abstruse Goose is one of my all time favorites.

It embodies my frustration at people who think that all  becoming a software programmer involves is learning a little computer syntax , reading a few books and typing out a lot of code.

The books that claim you can “Teach Yourself” X in Y “days/hours” etc are written by charlatans out to make a quick buck (I think sometimes it is the publishers that foist such titles on the authors in the hope to sell a few more copies). All they do is frustrate the people who are genuinely trying to learn software programming and provide PHB types with ammunition – after all if programming can be learned in X time then any schmuck who can read and knows a bit of typing should be able to become a programmer, at least by 2X the time.

Interestingly, no one writes a book on “Teaching Yourself” building a bridge or a skyscraper in X days – after all building construction is a popular metaphor in software engineering. The presence of these books are IMO a symptom of the ignorance that people have about what it takes to write solid software.

As this post points out – it can take up to ten years for an artist, researcher or a sportsman to be considered a master in his or her field. Software programming is no different.

How to write beautiful code

Beautiful code is elegant and simple – it is concise but clear. There is a balance in the code – a rhythm in the definition and structure of conditionals and the loops. The intent of the each function shines through the code – a pattern in the creation and interaction of the classes and methods in classes that combines the code into a coherent and beautiful unit. Beautiful code is concise, there are no wasted variables or endless conditionals – it is a pleasure to read not just because of the ease of reading but from the way in which it communicates the ideas and intent of the
programmer.

Well, now that I have waxed lyrical about what is good code, the next logical step would be to figure out how to write such code. Beautiful code starts with good understanding – in order to write beautiful code the first step is to understand the problem you are trying to solve. The next step is to have a clear idea of the solution and the approach you are going to take. These two things itself are entire subjects in software development – so I shall for the purposes of this post, assume that you have a clear idea of the problem you are solving and the approach you are going to take to solve the problem :-)

Even with these conditions met (understanding the problem and identifying the solution), sitting down in front of a blank page and writing out the excellent bug free code is almost impossible IMHO. The best programs that are out there are the result of an iterative process of coding and re-coding repeatedly – almost obsessively. Writing a program is like building a clay sculpture – you start of with a lump of clay, then you broadly shape it and  then keep removing and adding bits and pieces till you get your sculpture – sometimes you have to remove a big piece and add another instead and sometimes you simply throw everything  away and start over.

Writing beautiful code is hard – a seemingly simple algorithm like the Quick sort is the result of years of effort to come up with a concise and elegant implementation (in fact Quick sort has several implementations).  Even a simple piece of code like the quintessential “Hello World” program can be written in so many ways(in fact it is maintained as a separate GNU project).

So when do you stop iterating ?  There are some factors to consider in making this decision – usually if you are working on commercial software
this decision is not in the developers hands. The almighty deadline determines the ‘done-ness’ of your code – indeed, this seems to be
psychological impetus for a lot us. I have seen a lot of places and projects where people find it hard to work without a deadline looming,
like a Damocles sword, above their heads. Indeed I suspect there is something psychologically appealing to having this decision taken out of
our hands.

Again, for the purposes of this blog post, let us assume you have control over when you decide your code is done and you decide to release it only after you feel it is good enough. The question then becomes how do you know that what you have is beautiful code?

The first requirement of good code is, that it should work. If your code does not solve the problem it was intended to solve – you need to go back to the drawing board my friend – this is a necessary pre-requisite but it is not a sufficient condition for beautiful code.

One way to identify beautiful code is to read about programming – programming  methods, philosophies, etc.  I have book list of good software books to read you can start with (you can look at my post on internet reading for more book lists and articles).   In order to be a good sculptor, you need to know what beautiful sculpture look like – so you look at pictures of great sculptures – in fact this is usually a part of the curriculum for art programs. Similarly, sculptors look at examples of bad sculpture in an effort to recognize what to avoid.  So, in order to identify beautiful code look at examples of beautiful code – code written by great programmers and code written for great projects as well as bad code, ugly code.

Unlike sculpture – where you would have to travel to Italy to get a look at David or The Pieta – you have a lot of good code to read available at your fingertips – just open up the internet and look around :-) There are plenty of open source projects that share their code-base  – start with GNU, Sourceforge, and Google code (check out this post on the worlds oldest software repositories). If that’s not enough take a look at the examples in the ‘Code Complete‘ book (Other books you can look at ‘Beautiful Code‘, ‘Beautiful Data‘, ‘Clean Code‘ and ‘Coders at Work‘). Identify the patterns followed in beautiful code and the patterns you see in ugly code.

Another very important thing to recognize  is when you have stopped coding to a requirement. Good code is spare -it provides a solution to the problem at hand – no more – no less. A sign of good code is when you go through it and feel there is nothing you can remove from it – to paraphrase one of my favorite quotes by  Antoine St Exupery)  – “A programmer knows he has achieved perfection not when there is nothing left to add, but when there is nothing left to take away.”

And finally, the only way to make beautiful code is to write lots of code and publish it. All programs have constraints – some are technical and others logistical and yet others philosophical – good code is a elegant balance between these constraints.

So budding programmer –  Good Luck and Happy Coding !! I leave you with the following philosophy from the Python programing community –

The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

PS: I refer to coding and programing interchangeably in this post. What I mean by these terms is the act of writing a software program.

PPS: You can get the “Zen of Python” poem by typing “import this” at the interactive python console.

Update 1 : I found this link to a Ruby conference keynote where the speaker talks about beautiful code – Ruby is another language that has writing elegant code as one of it’s goals.

Update 2: Here is a great post on why you should spend the time and effort to write beautiful code :-)

Update 3: Here is a website from John Graham-Cumming where one can submit and read beautiful code.

Update 4: A great article on beautiful code by Brian Kernigham

What is TED ?

TED is simply a gathering of the remarkable minds to talk about and listen to ideas that they think are worth spreading.  At a glance these are the facts about this organization –

1. TED started out in 1984 as conference bringing together people from three worlds : Technology, Entertainment, Design.
2. It was acquired (in 2001) by a Non Profit – The Sapling Foundation. Under the foundation TED has evolved beyond a conference in Long Beach to a have global presence with conferences in US (TEDConference), Europe (TEDGlobal) and India (TEDIndia). The curator of the foundation (and the conference) is Chris Anderson.
3. The scope of the conference has also become broader to include subject matter, to cover almost all aspects of science and culture.
4. The conference is very difficult to attend and is by invitation only – in fact there have been claims that it is elitist and the folks at TED have responded to this claim.

All this is public record – but, IMHO what makes TED different is – the quality of the speeches and that they are publicly available on the internet.

The speakers at TED range from business tycoons like Bill Gates, Jeff Bezos, and Richard Branson to political figures like Bill Clinton, Al Gore and Gordon Brown to artists like Bono , Ze Frank and Frank Gehry (there are a lot more including Stephen Hawking, Jane Goodall, Nandan Nilekani, ….- you get the idea).  What moves them ? What excites them ? What do they feel is going to change the world ? These are the topics that they are invited to speak on for 18 minutes. There is a TED Prize – 3 winners are chosen every year from the conference and they get support from the TED organization for “One wish to change the world”. I guess there is something about the experience that seems to bring out the best from the audience, and the speakers, because the presentations made here are simply awesome !

The other aspect of TED and indeed the one that made me aware of them their potential is their endeavor to record and publish all the speeches on their website. The website was started in 2006 is constantly evolving with the latest social networking (Chris Anderson is on twitter) and awesome high quality video. This was what really made me go – whoa… and grasp the power of the conference. I suspect this is also what brought TED to the mainstream and captured the imagination of people like me, who would never have even heard of such a conference otherwise.

Some videos worth watching are –

1. Hans Rosling – Best stats you have ever seen
2. Pranav Mistry – Sixth Sense Technology
3. Karen Armstrong – Charter for compassion
4. George Whiteside – Postage Stamp Lab

There is some really inspiring stuff  here – I sincerely recommend that you bookmark this website and add it to your reminder list to visit on a regular basis – get motivated and inspired !!

Article, Video, TED

Quietube – Readability for videos

I was thinking a few weeks back, while wading though yet another banner ad heavy website to get to a video, about asking the folks behind Readability for something similar for videos. I filed away the thought for later and soon forgot about it (I think this is why I am not a millionaire ;-)).  Anyway, while going through other blog posts on Readability the other day I came across this one from a fellow Readability enthusiast from Brazil – right at the bottom was the link to this gem.  Et´ Voila ! Solution found – this is why I love the internet :-)

Quietube is exactly what I was thinking about – its Readability for internet videos !
Even the installation is similar –

1. Go to the Quietube installation page.
2. Drag the bookmarklet on to your bookmarks toolbar or add it to your bookmarks.
3. When you are in a one of the big internet video websites (YouTube, BBC iPlayer, Viddler, and Vimeo are supported) – click on the bookmarklet and you can see the video without any of the comments and distracting fluff.
4. A link is also available at the bottom of the page enabling you to send this view of the video to a friend or save it for further viewing.

The tool is built by BookTwo and from the blog post it seems its a side project inspired by Readability. The tool is currently limited, in that it does not detect embedded videos in other websites (and the error message seems a bit cheeky ;-)) but they are working on improving this. Another problem is that there seems to be no mechanism to report issues to the group like Readability. On the whole this seem to be a useful tool for those who want to quietly watch a video without all the bells and whistles :-)

web 2.0, software, tool, bookmarklet,

Readability – Transform the way you read on the web !

I love reading – I read books, articles, magazines, circulars, just about anything I can lay my eyes on… Naturally, I am a voracious reader in the Internet as well – I have subscribed to a huge number of RSS feeds, and  have a constant stream of Twitter tweets on articles to read.

The problem, I face when reading on the internet is, eye fatigue – I have astigmatism and the varying fonts faces, sizes and colors is a strain – even to normal people with perfect sight ! Couple this with the increasing number of advertising on the top and on the side of articles and you have a situation where the actual content is increasingly obscured. Font sizes are getting smaller and smaller and content is getting squeezed more and more by advertising and marketing clutter.

Of late, I have been using a tool that I found on the web (I saw it on Twitter but I have unfortunately been unable to track who sent it to me :-( ) that has literally transformed my reading experience. It was created by a company called Arc90 and is a Bookmarklet which can dragged onto your browser bookmarks. When you click on it – it  reloads the current page loaded in your browser stripped all extraneous fluff.  Simply the content of the page is shown.

As a web-developer and general internet addict ;-), I have seen a lot of tools and gadgets and I like to think I have a good idea of what works – as soon as I saw this tool I knew this would be awesome. The concept is simple, powerful – elegant.  It is one of those things
that seem so obvious  – when you feel that way – you know you are seeing a work of genius.

What you need to do to get this gadget is  –

1. Go to the Readability installation page
2. Choose from the simple options given there how you want your content to be displayed – the options are simple and straightforward giving you a choice of reading style, font size and margin width (I chose eBook style, large size and narrow margin). A sample text is shown with the formatting you choose so you can play with the options.
3. Once you are satisfied, simply drag the big button marked “Readability” onto your bookmark toolbar (or you can right click the link and choose the bookmark option) and your done !
4. Next time you are on a web-page with a compelling article being obscured by garish ads and decorations, simply click on the Bookmarklet and the page reloads with the content formatted exactly as you want it.

When I first installed it they had fewer options and every once in awhile it would not work – but they have been going from strength to strength with new options and it’s rare to see it not work.

This tool has certainly transformed how I read on the web – I can’t recommend this tool enough!!  So what are you waiting for – go get it !! :-)

PS: It won the NY Times Pogy award for best idea of 2009

web 2.0, software, tool, bookmarklet, font

A podcast review – Software Engineering Radio

I am a fan of podcasting.. video blogging and screen casts are fine, but in terms of convenience and bang for the megabyte – nothing beats a podcast :-). I have been listening to podcasts for a few years now. I am usually listening when walking home from work or doing some chores. In fact I wrote an earlier postabout them along with some of my favorites (at the time).Of late I have listened a lot to a podcast called Software Engineering Radio. Actually, I have been listening to this one for a long time now and it has grown from strength to strength. It was started by a German software consultant – Markus Voelter and is based in Europe (the details are here). There is now a team of people both creating episodes as well as supporting the website. A new episode is published every 10 days and the feed for it is available at the website.

The podcast is about the software engineering and is for professional developers (it says so in the title :-)).  IMHO it is the best podcast for professional developers I have come across.  Markus and his team of volunteers do a great job – the interviews are professionally done and the audio quality is great. The post production is also very well done – in fact they have put up videos about their recording and post-production process. All the recording are released as part of Creative Commons 2.5 license and I think the majority of the episodes are gems worth downloading and keeping.

The coolest thing about Software Engineering Radio and what ultimately makes it such a great resource are the subjects and the people they interview.

The subjects are for the most part about software engineering practice – but they are things that are really useful to ones growth as a software professional. Episodes range from discussions about software development methodology to software languages and tools to computer science research.  In fact there was recently a very interesting episode on the – Difference between Software Engineering and Computer Science.

The people interviewed range from professional software developers and consultants to researchers and academics. Some are giants in their field and others I haven’t heard of (admittedly thats a large percentage of them – maybe because I hadn’t heard of their field in the first place ;-)).

Another thing I would like to mention is the format of the episodes. They are interviews and the team at SE Radio
go to great lengths to prepare and ask just the right questions to
illuminate the topic at completely and extract pearls of wisdom from
the people they interview. I think this format is better than a speech or a presentation because of the interaction between the interviewer and the interviewed.

There is sometimes a problem with the English accent – most of the team are from mainland Europe and have European accents, but it is never so bad that one cannot understand what is being said. In fact one of the things I like about the show are the various accents of people from different parts of Europe, UK and America. It makes the show more interesting to me as I try to guess at the nationalities of the interviewer and interviewed from their accents ;-)

Software Engineering, podcast, review