travisjeffery + programming 154
Kendo UI - a framework for modern HTML UI | Hacker News
8 weeks ago by travisjeffery
If you take away how this looks, and start digging into the project from a beginner's perspective, this project is awful. I find this with most of the supposed "UI frameworks" out there for HTML. With a few exceptions, they mostly lack:
1. Good documentation that doesn't just define the framework, but teaches you how to use it and get stuff done with it. Code already defines what it is, your docs should tell me why it's this way and how to use it. In Kendo UI they've got a list of dependencies for javascript projects they need, then a few code snippets with no explanation as to why or how they work.
2. Good sample code, in a full complete project you can download, with documentation on getting it up and running. Your first sample code is how everyone will write code using your project. If you've got bad samples, poor formatting, and weird file layouts (or none), then that's what everyone will write and that's what you'll be known for.
3. Examples that gradually increase in complexity. Start off with a simple hello world, graduate to a chat app or something simple, and get them to a full blown large application. In this Kendo example they've got a demo picture viewer, with no explanation for how it was built, and viewing the source it looks like a huge mess.
4. Humor. These kinds of documentation are boring as hell, especially if you're just defining everything. It doesn't have to be insanely hilarious, but at least throw a few little funny tidbits in the code. Even the great tech books of our time have tiny little jokes for the people who pay attention.
5. Finally, these frameworks rarely have a "theme". MVC is a theme. Convention over configuration is a theme. There's only one way to do it. There's more than one way to do it. Themes work to help people keep the script for why everything works the way it does in their head.
It's too bad because this looks really good, and it could be the most awesome thing on the planet. But if I can't figure it out even if I want to, then I'm never going to try.
Finally, none of what I wrote above applies if your project is for fun and not meant to be a "product".
zedshaw
writing
programming
frameworks
libraries
1. Good documentation that doesn't just define the framework, but teaches you how to use it and get stuff done with it. Code already defines what it is, your docs should tell me why it's this way and how to use it. In Kendo UI they've got a list of dependencies for javascript projects they need, then a few code snippets with no explanation as to why or how they work.
2. Good sample code, in a full complete project you can download, with documentation on getting it up and running. Your first sample code is how everyone will write code using your project. If you've got bad samples, poor formatting, and weird file layouts (or none), then that's what everyone will write and that's what you'll be known for.
3. Examples that gradually increase in complexity. Start off with a simple hello world, graduate to a chat app or something simple, and get them to a full blown large application. In this Kendo example they've got a demo picture viewer, with no explanation for how it was built, and viewing the source it looks like a huge mess.
4. Humor. These kinds of documentation are boring as hell, especially if you're just defining everything. It doesn't have to be insanely hilarious, but at least throw a few little funny tidbits in the code. Even the great tech books of our time have tiny little jokes for the people who pay attention.
5. Finally, these frameworks rarely have a "theme". MVC is a theme. Convention over configuration is a theme. There's only one way to do it. There's more than one way to do it. Themes work to help people keep the script for why everything works the way it does in their head.
It's too bad because this looks really good, and it could be the most awesome thing on the planet. But if I can't figure it out even if I want to, then I'm never going to try.
Finally, none of what I wrote above applies if your project is for fun and not meant to be a "product".
8 weeks ago by travisjeffery
Wil Shipley: Writing If Statements
march 2011 by travisjeffery
What you should really do is write "if" statements that check for improper conditions, and if you find them, bail. This cleans your code immensely, in two important ways: (a) the main, normal execution path is all at the top level, so if the programmer is just trying to get a feel for the routine, all she needs to read is the top level statements, instead of trying to trace through indention levels figuring out what the "normal" case is, and (b) it puts the "bail" code right next to the correctness check, which is good because the "bail" code is usually very short and belongs with the correctness check.
When you plan out a method in your head, you're thinking, "I should do blank, and if blank fails I bail, but if not I go on to do foo, and if foo fails I should bail, but if not i should do bar, and if that fails I should bail, otherwise I succeed," but the way most people write it is, "I should do blank, and if that's good I should do foo, and if that's good I should do do bar, but if blank was bad I should bail, and if foo was bad I should bail, and if bar was bad I should bail, otherwise I succeed." You've spread your thinking out: why are we mentioning blank again after we went on to foo and bar? We're SO DONE with blank. It's SO two statements ago.
if
statements
objective-c
programming
When you plan out a method in your head, you're thinking, "I should do blank, and if blank fails I bail, but if not I go on to do foo, and if foo fails I should bail, but if not i should do bar, and if that fails I should bail, otherwise I succeed," but the way most people write it is, "I should do blank, and if that's good I should do foo, and if that's good I should do do bar, but if blank was bad I should bail, and if foo was bad I should bail, and if bar was bad I should bail, otherwise I succeed." You've spread your thinking out: why are we mentioning blank again after we went on to foo and bar? We're SO DONE with blank. It's SO two statements ago.
march 2011 by travisjeffery
related tags
administration ⊕ adroid ⊕ ajax ⊕ algorithm ⊕ algorithms ⊕ api ⊕ apple ⊕ applescript ⊕ article ⊕ bash ⊕ BBC ⊕ beats ⊕ beep ⊕ billgates ⊕ blog ⊕ blogs ⊕ book ⊕ books ⊕ bot ⊕ bots ⊕ bundle ⊕ bundles ⊕ business ⊕ c ⊕ c++ ⊕ calendar ⊕ career ⊕ cheatsheet ⊕ cli ⊕ clojure ⊕ CMS ⊕ cocoa ⊕ code ⊕ coding ⊕ collaboration ⊕ college ⊕ commands ⊕ community ⊕ company ⊕ competitions ⊕ compilers ⊕ compsci ⊕ configuration ⊕ consulting ⊕ coredata ⊕ cpan ⊕ cs ⊕ css ⊕ data ⊕ database ⊕ Dev ⊕ developers ⊕ development ⊕ digg ⊕ django ⊕ documentation ⊕ ebook ⊕ ebooks ⊕ ecommerce ⊕ editor ⊕ editors ⊕ education ⊕ ego ⊕ elisp ⊕ emacs ⊕ email ⊕ entrepreneurship ⊕ environment ⊕ esr ⊕ essay ⊕ essays ⊕ example ⊕ examples ⊕ exercise ⊕ exercises ⊕ extensions ⊕ facebook ⊕ finance ⊕ font ⊕ fonts ⊕ form ⊕ format ⊕ framework ⊕ frameworks ⊕ free ⊕ freelance ⊕ fun ⊕ functional ⊕ funny ⊕ fxruby ⊕ Geek ⊕ gem ⊕ geo ⊕ git ⊕ gmail ⊕ god ⊕ google ⊕ graphics ⊕ gtd ⊕ gui ⊕ guide ⊕ hacker ⊕ hackers ⊕ hacking ⊕ hash ⊕ haskell ⊕ how-to ⊕ howto ⊕ html ⊕ Humor ⊕ ide ⊕ if ⊕ insight ⊕ inspiration ⊕ internet ⊕ interview ⊕ interviewing ⊕ ios ⊕ iphone ⊕ irc ⊕ Java ⊕ javascript ⊕ job ⊕ jobs ⊕ jquery ⊕ language ⊕ Languages ⊕ learn ⊕ learning ⊕ leopard ⊕ libraries ⊕ library ⊕ life ⊕ linux ⊕ lisp ⊕ mac ⊕ macosx ⊕ mail ⊕ microsoft ⊕ mistakes ⊕ mixes ⊕ modules ⊕ money ⊕ mongrel ⊕ monospace ⊕ mootools ⊕ music ⊕ mustread ⊕ mutt ⊕ mvc ⊕ mysql ⊕ network ⊕ nu ⊕ objc ⊕ objective-c ⊕ objectivec ⊕ oop ⊕ opensource ⊕ oreilly ⊕ osx ⊕ panic ⊕ paypal ⊕ people ⊕ perl ⊕ peternorvig ⊕ php ⊕ plugin ⊕ plugins ⊕ pocketprogramming ⊕ productivity ⊕ programming ⊖ puzzle ⊕ Puzzles ⊕ python ⊕ qt ⊕ quartz ⊕ quartzcomposer ⊕ questions ⊕ rails ⊕ random ⊕ refactoring ⊕ reference ⊕ regex ⊕ regexp ⊕ religion ⊕ research ⊕ resource ⊕ resources ⊕ ruby ⊕ rubyonrails ⊕ science ⊕ scm ⊕ screencast ⊕ screencasts ⊕ script ⊕ scripting ⊕ scripts ⊕ search ⊕ security ⊕ shell ⊕ skill ⊕ snippets ⊕ sockets ⊕ software ⊕ spaces ⊕ sql ⊕ stanford ⊕ startup ⊕ statements ⊕ statistics ⊕ stevejobs ⊕ stories ⊕ story ⊕ subversion ⊕ svn ⊕ tabs ⊕ tdd ⊕ tech ⊕ testing ⊕ textmate ⊕ tips ⊕ to-read-later ⊕ todo ⊕ tool ⊕ tools ⊕ toread ⊕ towatch ⊕ tricks ⊕ tutorial ⊕ tutorials ⊕ twitter ⊕ typography ⊕ university ⊕ unix ⊕ useful ⊕ usergroup ⊕ vi ⊕ video ⊕ vim ⊕ vimrc ⊕ web ⊕ web-d ⊕ webdesign ⊕ webdev ⊕ webdevelopment ⊕ wiki ⊕ writing ⊕ youtube ⊕ zedshaw ⊕Copy this bookmark: