I want to use this opportunity to open a discussion and get hacker news community's thoughts on preparing code examples.

I always find many contrieved examples in coding guides such as:

  class Bicycle
    def initialize(size_of_wheels)
      # blah
    end

    def run
      # blah
    end
  end

These are fine. But as such, the examples always fit well with the principles and you try to implement the principles, reality is a always far more messier.

Are there a better way to write coding examples? does it ever make sense, to grab snippets from a real code base and so that it is in touch with reality