MarkDown, Textile, RDoc, choose your foe

Recently i used all 3 of them for various project documentation, and somehow all of the are broken…

MarkDown

Pro:

  • Looks like natural text
  • Simple, mostly elegant syntax

Con:

  • Lists can destroy your layout, try this:
     - test
    
    ### Heading

    The heading will be in your list, thats just wtf… (adding <span></span> before the heading helps)

  • No tables…
  • Some editors truncate the double space used for linebreaks
  • No numbered list, except you add 1. 2. etc yourself

Textile

Con:

  • Looks weird with h2. h3. but thats kind of ok…
  • You need a free line after each heading, which makes the layout look bloated, especially if you got a lot of sub-headings
  • Line break = <br /> very elegant…

RDoc

Pro:

  • You can use your RDoc skills for documenting ruby

Con:

  • No linebreaks, not even <br/> works….
  • to highlight code you have to use <tt>CODE</tt> very elegant…

All

  • You can use html to hack most of the things that do not work, but that somehow defies the purpose…

So my personal favorite is markdown, elegant, and if you know you have to look out for those lists its somewhat ok…

But if possible i would switch to RDoc, since then i would not have to make a mental switch while documenting code.

Id like to hear your opinion, or at best a “no thats wrong, you can do xxx with yyy” 🙂

Programming Perls Rewritten in Ruby

Just for a little exercise i am doing the programming pearls examples/tasks in ruby, and so far it has been funny/challenging.
Source is on github

Trivial examples

#displaying all words from STDIN
#C++
int main(void)
{   set S;
    set::iterator j;
    string t;
    while (cin >> t)
        S.insert(t);
    for (j = S.begin(); j != S.end(); ++j)
        cout << *j << "\n";
    return 0;
}

#Ruby
puts STDIN.readlines(' ').uniq * "\n"

ruby is my winner 😀

Spammers arrive on Github

Hello,
Nice to meet you, how is everything, hope all is well with you. My name is Madam Avelin Regato, 
I found your contact after reading your profile I picked interest to contact you. I've something 
very important which I would love to share with you privately, therefore, would advise you to 
kindly write me back on: (avelin_regato7@yahoo.com) so that I'll give you details. 
Waiting anxiously for your anticipated corporation,
Yours,
Madam Avelin
Email me on: avelin_regato7@yahoo.com

Finally spammers have arrived…

Hopefully the github team has some counter-measures up their sleeves…
A search for this spam only returns 1200 results, but none in combination with github seems to be new…

Grabbing Zen and the Art of Motorcycle Maintenance

I just found “Zen and the Art of Motorcycle Maintenance” for free online, a book that was on my wish list for quiet some time (recommended by a good number of programmers…).

And since i like a printed version here is a small script to get it in a printable format.
(which i post here for educational purpose only)

require 'rubygems'
require 'open-uri'
require 'hpricot'

book = 'zen_and_the_art/zen_and_the_art'
pages = 32
text = ''
1.upto(pages) { |i|
  doc = Hpricot(open("http://www.esolibris.com/ebooks/#{book}_#{i.to_s.rjust(2,'0')}.php").read)
  doc.search('table.body tr td[@height=40] div').remove
  doc.search('table.body tr td[@height=40] img').remove
  doc.search('table.body tr td[@height=40] p.body').remove
  doc.search('table.body tr td[@height=40] p a').remove
  part = doc.search('table.body tr td[@height=40]')
  text += part.inner_html
}

File.open('out.html','w') {|f|f.puts text}

The Black White Tree Testing Method

snow tree by plain ethos

TDD often is well understood, but seldom put to good use. Spikes grow larger, hard to test aspects are skipped and sooner or later your test coverage looks like this.

.

Therefore i want to show you the Black-White-Tree testing method, which is easy to adopt and results in full C1(path) coverage with easy to maintain, independent tests.

.

.

ice tree by serendipitypeace2007

ice tree by serendipitypeace2007

The principle is simple:

When designing a new method build Black-Box tests for it, often 2-3 are sufficient if they exersice all paths within this method(not necessarily its sub-methods), represented by the trunk and the black branches.

describe :price do
  it "sums prices and applies discounts" do
    Order.new(:items=>items,:discount=>20).price.should == 22.5
  end
  it "costs nothing if it is free" do
    Order.new(:items=>items,:free=>true,:discount=>10).price.should == 0
  end
end

Then write White Box tests, for the public method, mocking everything out with forged return values to verify that every method is called and the call-results are used logically.

describe :price do
  ...
  it "uses sum_price and apply_discount" do
    order = Order.new(:items=>items,:discount=>10)
    order.expects(:sum_prices).returns 100
    order.expects(:apply_discount).with(10,100).returns 20
    order.price.should == 20
  end
end

Then build the method, making all White Box and some of the Black Box tests pass.
Repeat for every sub-method.