EZTABLE IDEAS 是 EZTABLE 成員揮灑熱情和大家分享專業及創意的網誌。 EZTABLE 讓消費者 24 小時都可以在網路訂位全台灣最優質的餐廳,同時提供餐廳經營者 e 化的訂位管理系統 (雲端、iPad、智慧型手機)

Learn to Read the Source, Luke

五月 08 2014 Published by under Engineering

Yoda: Learn to Read the Source, Luke

Learn to Read the Source, Luke

 

At EZTABLE, we embrace the culture of open-source software (OSS). Believe it or not, finding a software with good documentation is way harder than finding a software that actually works. However, one fundamental aspect of OSS is that source codes are always included. Quoting from Jeff Atwood:

 

No matter what the documentation says, the source code is the ultimate truth, the best and most definitive and up-to-date documentation you’re likely to find. This will be true forever, so the sooner you come to terms with this, the better off you’ll be as a software developer. — Jeff Atwood, Co-founder of Stack Exchange and Discourse

 

Most of OSS we use have some kind of test suites. Fortunately some even follow the BDD/TDD convention of describing a self-documenting use case in each test. Here we use the test case from Koa.js as an example:

 

it('should respond with a 404 if no body was set', function(done){
  var app = koa();

  app.use(function *(){
    // noop
  })

  var server = app.listen();

  request(server)
  .head('/')
  .expect(404, done);
})

 

There is no doubt how the program is designed and should behave. As Chinese, we might not be fluent in English, but as engineers, we certainly know how to code.

 

This is how I read the code:

  1. Read the documentation, README.md, and GitHub issue.
  2. If (1) does not answer my question, read the test suite.
  3. If both (1) and (2) does not answer my question, read the annotated source.

 

Reading Jeff’s blog leads me to another brilliant post at Hacker News by Brandon Bloom:

 

Sometimes, the documentation isn’t complete. Sometimes, it’s wrong. The source code never lies. For an experienced developer, reading the source can often be faster… especially if you’re already familiar with the package’s architecture. I’m in a medium-sized co-working space with several startups. A lot of the other CTOs and engineers come to our team for guidance and advice on occasion. When people report a problem with their stack, the first question I ask them is: “Well, did you read the source code?" …… When you run a business, if your software has a bug, your customers don’t care if it is your fault or Linus’ or some random Rails developer’s. They care that your software is bugged. Everyone’s software becomes my software because all of their bugs are my bugs.

 

Enough said. In the end, another quote from Jeff Atwood:

 

We must read other people’s code because we have to understand it to get things done. So don’t be afraid to read the source, Luke – and follow it wherever it takes you, no matter how scary looking that code is.

 

May code be the common language among us.

by hden@eztable.com

Further Reading

Here are some of the extraordinary well written codes:


Related Posts Plugin for WordPress, Blogger...

No responses yet

發表迴響