Yes, it takes some time and discussions between the disciplines but you can win so much time in the future if done right. Doing stuff right depends on some crucial things:

• Work interdisciplinary and as (almost) equals. It’s easy to say what you think out the whole plan yourself, but if you do that, others are not inclined to think with you. Each new idea becomes just another bump in the project instead of a good contribution to a discussion to get a better understanding of a problem. By putting your problem on the table and make team members real team members, you get a real discussion. And a better product in the end
• Make your work public. You also get a whole other situation if you know that other people (clients or the community) are keeping an eye on you. In the positive sense of the word, that is. You have to think (just like Twitter) what is really useful outside your little bubble. And you might get good feedback to make your code even better/stable/useful.
  By thinking hard how to make stuff usable for the outside world, you’re instantly making a very usable and learnable tool for anyone who’s going to work at your firm.
  Making open source software could also motivate people. They’re not just working hard for the company anymore, they’re also working on something that can also be useful outside of the company and the greater good. That can be the motivation to work a more on it outside work time.
• Results before deadlines or budget. Ok, projects with limitless budgets aren’t realistic. But making reusable code or applications without keeping an eye on its usability or not even testing isn’t realistic either. To get quality reusable code you do not only need to write it, you have to think it out, write it and rewrite it and rewrite it. If you’re not prepared to do that, just save yourself the trouble.
• Continuous testing. Don’t wait until the very end of the project to measure its quality. You cannot remove the concrete slabs below an ill-constructed house either. Everybody has to at least check the end result of the finished component before moving on to the next target.
• Reusability is epic. Don’t kid yourself: Most of the stuff you do now has been done in the past as well. Talk with designers, programmers and developers to aim for reusability while preventing that all websites start to look the same. Getting some framework that works for everybody is everybody’s priority.
• Keep it simple. Some projects need solid plans. Others don’t. Some stuff does not have to be written out in threefold as long as the basics are known and the outer borders have been drawn. Be wary if the 5th version of the plan is mailed in PDF form to all team members, project time already gets out of hand and no real work is done yet.

No related posts.

Problems with my current codebase

Well, I already have a codebase, but it has some problems. The important one is that it only covers the very basics. That’s because designs can be very diverse and as a developer I want to stay true to the design. So it’s hard to build a codebase with grids and blocks if all design differ from eachother.

Another problem major issue is something I have more control over: the codebase and the documentation is a bit scattered. The last problem I have is that I have no demo page of my standard CSS code, so there’s no easy way to check the template on browser compatibilities.

Now my jQuery plugin project has reached version 1.1, I had the time to do some thinking about a new codebase that would be solid, extendable, easy to deploy and would replace all other codebases and documentation.

Let me make it clear: this article is about my considerations about building a solid framework for myself. It may not apply to you and my ideas not unique either. It still may be helpful for you to get an idea of what sort of codebase you need.

Existing examples

The most important thing about a codebase is to decide how to set it up and how to store it. I like the way open source grids like Grid960 and YUI have organized their code into little reusable bits and have created a demo and test page for each and every component.

I must admit: I hardly ever used these grids. Most of those grids talk the language of the web developer, not of the designer. And the designers I know don’t have to limit themselves to a 24-column grid system. Not to mention the designers that are totally ignorant of such a system and whose task is to design a website and mail the Photoshop file to some other company that has to build it. Although I have my reservations towards grids, I like the way these codebases are organized. It can serve as a good Blueprint for my own codebase.

I also get my inspiration from Nicole Sullivan’s talk on Object Oriented CSS (OOCSS). OOCSS basically means that you build your components in such a way that they become extendable objects. Just like in real object oriented programming. Just have a look at her talk about OOCSS on Yahoo! Developer Network.

Prefix classes

By adding a (relatively) unique string before the name of the class you have created your own CSS namespace. It will minimize any interference of other CSS styling that is not part of your own code. Some real life examples can be found in the code that is generated by the CMS systems I have experience with: Sitefinity and Sitecore. The CMS Sitefinity for example prefixes all CSS classes with “sf_”.

Grids, blocks and text

All CSS code will be split into different categories that work relatively independently of each other. Until now I can come up with 3 of them.

Grids

Grids are the frameworks of placeholders in which we put our content. You know: header, visual, column1, column2, column3 and footer. There are lots of grid templates around like Grid960 and Blueprint. My view is that those templates only work if the designer agrees to work within the limits of that framework. My ambition is to write a framework that makes my work easier while still being flexible enough to keep the designers happy.

Blocks

There are as many block as the designer can come up with. I think it will be a real time saver to talk with the designer and write down all the types of blocks he thinks he’ll like to use often. Or even better: just open the last 20 or so web designs he/she made and destil the common blocks and its common features. like menus, news article lists, homepage spotlights, etc. Finally you create basic blocks of it in your template system.

Standarization is not always popular with designers but if it means that projects can be created cheaper there may eventually be budget left to build cool stuff. At least, I hope…

Text

Basic text styling is also a relatively independent component in CSS code. You always define a basic font color, family, size and line height that serves as a base styling for the whole websites. More specific text styling in blocks should be kept to a minimum and preferably relatively to the base text style. So if you have a base style of font: 1em/1.5em normal Arial, sans-serif, you ideally should style a header in a block like this: font-size: 1.5em; line-height: 1.2em;.

Although font-weight is not something you can set relative to a base style, it’s not likely that it will look ugly in combination with some design if you add font-weight styling to a block. Setting the font-family in the styling of blocks on the other hand will most likely interfere with design, since designs tend to depend heavily on a particular font.

Create base templates and extend themes

The code for each grid system and each block will be stored in a seperate base CSS file. Each grid or block can be extended with extra themes or styles. Each style extension will have its own CSS file and presumes that the base file is already loaded.

Optimizing CSS

Having all code seperated in small snippets is great for maintaining an overview. As long as you can see what a CSS file does by looking at its filename, its will be easy to add and extend styling to a website.

The template code is not optimized for speed, though. If we don’t do anything about the fragmentation, the server will have to load a bunch of little CSS files. It’s important to stress this: It’s not just the total filesize that matters, each http request costs time. Check out YSlow if you want to know more about this and if it affects your site.

YUI

That’s why all CSS in the website has to be exported, merged and its code minified to one single CSS file. Normally I use YUI compressor for it.

Less

But you can do more than just minification. Less is a system that extends the CSS syntax with stuff like variables, nested rules and mixins. Less was originally built in Ruby, but there’s also an ASP.NET port. I hope it will help me create very flexible grids.

By exporting CSS into optimized code, you can focus on making the most readable CSS source file because all comments and spaces in the code will be removed in the end. This is also what I do with JavaScript code and certainly will continue to do.

Related posts:

1. Too advanced CSS selectors
2. The last resort in CSS debugging
3. Tips for using and debugging of Less CSS code
4. Crucial stuff for your company’s internal projects

Related posts:

1. Another Codeview update
2. Codeview update
3. Codeview, a new template for JSDoc Toolkit
4. Codeview 1.2
5. The jQuery plugin Ono List Pager reached version 1.0!

• A quick filter, to filter the class list and methods
• Extra command line options, thanks to Aaron Wirtz
• A more logical template structure, thanks to Aaron Wirtz
• Some bug fixes, including one reported by Gregor

Go to the download page.

Related posts:

1. Codeview, a new template for JSDoc Toolkit
2. Codeview update
3. Another Codeview update
4. Codeview is on Github now

So I just wanted you guys to know that there’s a minor bugfix for Codeview

Go to download page

Related posts:

1. Codeview update
2. Codeview, a new template for JSDoc Toolkit
3. Codeview is on Github now
4. Codeview 1.2

• Support for mobile devices
  Through the use of CSS media queries.
• Updated design
  • The left menu remains in view when scrolling down the page (in most browsers anyway)
  • Namespaces in left menu will wordwrap
  • Headings now have a custom font: M+

Go to download page

Codeview for desktops

Codeview for handheld devices

Related posts:

1. Codeview, a new template for JSDoc Toolkit
2. Another Codeview update
3. Extending media queries with JavaScript
4. Codeview is on Github now
5. Codeview 1.2

The template is based on the basic template of JSDoc Toolkit. The HTML structure is basically the same, but with a new design for both desktop and mobile browsers.

Command line options

• Set title -D="title:Estate Library"
• Remove _global_ -D="noGlobal:true"
• Make “Files” the homepage instead of “Classes” -D="index:files"

Example:
java -jar jsdoc-toolkit\jsrun.jar jsdoc-toolkit\app\run.js -d=Documentation\ -D="noGlobal:true" -D="title:Estate Library" -D="index:files" -t=jsdoc-toolkit\templates\codeview -p -v Javascript\Estate\Source\Estate*.js

Screenshots (version 1.1.2)

Codeview for desktops

Codeview for handheld devices

Changelog:

• 1.2
  - Extra command line options, thanks to Aaron Wirtz
  - A more logical template structure, thanks to Aaron Wirtz
  - A quick filter, to filter the class list and methods
  - Some bug fixes, including one reported by Gregor
• 1.1.2
  - Option for removing the _global_ link by adding -D="noGlobal:true" in the command line
• 1.1.1
  - Styling fixes
• 1.1
  - Support for mobile devices
  - Updated design and styling fixes

Related posts:

1. Codeview 1.2
2. Codeview update
3. Document your Javascript: interview with Michael Mathews of JSDoc Toolkit
4. Codeview is on Github now
5. Another Codeview update

Michael Mathews

I recently discovered JSDoc Toolkit, a tool that generates documentation of your Javascript code in the form of a website. That was dearly needed because I wanted to give me and other team members a better overview of my growing JavaScript codebase.

The history of JSDoc

The JSDoc-toolkit and its predecessor JSDoc have been around for nearly 10 years now and in both cases the bulk of the code is programmed by Michael Mathews, often shortened to “micmath”. JSDoc started as a solution for the growing Javascript code at the company he worked for: “I couldn’t find any existing tool that did what I wanted, so I just naturally started building my own. I didn’t want to totally reinvent the wheel of course. I basically tried to port Sun’s JavaDoc idea over to JavaScript.” So he wrote a documentation tool in Perl. “Once it was done and we’d used it a bit, I decided to release it as open source on SourceForge. I figured if I found it useful then maybe someone else would as well.”

Although JSDoc is a very useful documentation tool and probably the first free tool as well, it wasn’t received that well back in 2001 according to Michael Mathews: “It seemed the general JavaScript community was not yet ready for JSDoc. Back then the majority of folks doing JavaScript were not in the habit of practicing what you would call ‘Software Engineering’ best practice! It was, more often than not, a field dominated scripting cowboys. The idea of automatic documentation generation, I think, was seen as something unneeded by most. According to the stats from SourceForge, the JSDoc tool was only downloaded a few hundred times in the first several years – and frankly that already seemed amazing enough to me.”

The renaissance of JavaScript

But as the web got more mature, so did the developers. Javascript gained respect in the last few years and the emerge of large libraries such as YUI, jQuery and Prototype showed that Javascript can be used in a complex but constructive way. New ways of coding were used to structure Javascript. Michael noticed the trend: “Since about 2005 JSDoc really started to take off. Since then it’s been downloaded over 30,000 times. It still seems amazing to me.” The latest version of JSDoc Toolkit is downloaded almost 5000 times since it was published in September 2009.

JSDoc in the wild

The term JSDoc by the way is a bit confusing. It refers both to the syntax and the program. The syntax has been relatively successful as well: “I know that a few of Google’s projects use JsDoc comments to extend their functionality. Closure Compiler is a good example of that, though it can be a pain when other projects start redefining the JsDoc syntax for their own purposes in ways that are incompatible with the original project. Of course there is no official standard for JsDoc comments, so I can’t blame them, but that is something I’d really like to see: an official JsDoc standard, I mean.”

“The idea of JSDoc has been picked up by many large projects over the years. However, my application was originally written in Perl and wasn’t very flexible, consequently it got rewritten by others a few times for internal use only. I don’t want to name any names because I personally think that, while perfectly legal to do that, it violates the open source spirit I intended the work to be used in.”

Document your code...

...run the tool...

...and publish the generated documentation website.

The Toolkit of JSDoc

A year after JSDoc was released, Michael resigned as an active contributor to the project. Gabriel Reid took care of JSDoc after that. He maintained and extended it. But around 2006 Michael decided to do a major upgrade for JSDoc. “Big frameworks were the norm and along with that was both the need for API documentation as well as the complexity of writing documentation for all the new and interesting things people were doing with JavaScript. I was beginning to think that, in order to get JSDoc up to speed with this new world, it would need to be rewritten from scratch. So I started a discussion about that on the users’ list. That eventually led to the current incarnation of the project: JsDoc Toolkit.”

The rewrite was written in Javascript itself. That was possible with the open source Rhino platform that parses the Javascript. That wasn’t based on any technical issue: “I just liked the idea of a program parsing itself. As a bonus the users were more likely to be able to modify the source code if it was written in a language they work in.”

Rhino runs on Java and was initially developed by Netscape. Rhino would have been a part of a larger project to port Netscape Navigator to the Java platform, but that never happened. Rhino is still being used and is maintained by the Mozilla Foundation.

How JSDoc works

JSDoc reads the code and the comments. The comments need to be formatted according to the JSDoc convention. It’s a notation that’s used in other tools like Google’s Closure as well and is similar to the JavaDoc convention.

The comments give hints to JSDoc Toolkit how the JavaScript is structured. Unfortunately not all notations are recognized by the tool. In fact: most of the really exotic notations are not recognized. Michael: “People don’t realize how difficult it can be to do static code analysis on a language as dynamic as JavaScript. Well, at least I didn’t. It is provably impossible in most cases to know what the various states of a JavaScript program will be at runtime, just from looking at the source code. I tell people, if you can get a program to know what you want have programmed, just from the plain source code, consider yourself lucky!”

“But for the rest of us JsDoc Toolkit provides a way to document your code in such a way that the tool never has to even see your code. In fact, you can even use JsDoc Toolkit in files with just comments, no code whatsoever! So in that sense there isn’t any code you can’t document with JsDoc Toolkit, as long as you don’t rely on the static code analysis features.”

The word “Toolkit” in the name “JSDoc Toolkit”, by the way refers to the template engine JSPlate. Michael: “I eventually went with the ‘Toolkit’ name mostly because I liked the sound of it, but also as a little nod to a favourite templating system of mine, Andy Wardley’s Perl Template Toolkit.”

JsDoc Toolkit Version 3

Right now Michael is in the middle of programming version 3 of JSDoc of which the first beta should be released somewhere this summer. “Basically there are a few feature requests from JsDoc Toolkit 2 that seem reasonable enough -things like documenting the same symbol more than once- which are utterly impossible due to the core architecture of the tool itself. All those feature requests are now on the table and I’ll try to include them in the new version.”

“One feature that will definitely be supported is the idea of overloaded functions. A typical example would be a function named ‘width()’ that returns the width when it is called with no arguments, but will set the width when called with a numeric argument.”

“This is fundamentally not possible to document in JsDoc Toolkit Version 2. And that really is the point of rewriting the tool for Version 3: it will include, in it’s core, all the lessons learned from the past several years of supporting JsDoc Toolkit. I believe it will provide a much more flexible foundation to build on.”

In addition, Michael will make more use of Rhino than he already did. Until now Rhino was only used to parse the server-side JavaScript. The parser that walks over the source code looking for doc comments and things like function declarations was written by Michael himself. Rhino has a JavaScript parser built in, but it would took “some serious Java hacking” to get it right.

“Fast forward a few years and some important things have changed: namely, Norris Boyd has made accessing Rhino’s internal Abstract Syntax Tree much easier. In fact, it is now as easy to walk over your source code as it is to use, say, DOM nodes to walk over HTML. I’d be crazy not to take advantage of all that free power just sitting there waiting to be used!”

“So Version 3 will have none of my own parser left in it. This means I get to shed about 40% of the project’s code, which was dedicated to just that one task, and can now focus on the more important bits: parsing the doc comments.”

“It also means that, in theory, if Rhino can understand it, you’ll be able to get JsDoc Toolkit to understand it. Of course this is all taking time to get up to speed with, but I’ve decided to use build my tool on top of the new RingoJS framework and that’s made my life much easier, and the process much faster.”

The first beta of version 3 is estimated to be released in early summer.

Continuation

One of the weak spots of the JSDoc project is that most of the time there’s only one active developer working on it. Although the tool is still alive and kicking, it naturally needs some nurturing to prevent it from getting stale. “To be honest it can feel like a real burden sometimes.” Michael admits. “It’s essentially just me these days, and I mostly can’t give the project all the time it deserves.” So developers are welcomed to join in the project: “I’m ready to sign them up! The fact is that I think of JSDoc as my baby. Not that I invented anything new or amazing, I most emphatically didn’t. But I’d lived with it long enough and I’d become associated with it, so I wanted to see it do well in life.”

And so the development continues even though there are now some other tools around like JSDoc. He even used some of them. “I used to write a lot of Perl and JavaScript at the same time and found NaturalDocs to be a great tool because it required a single format that could work in any language.”

Server side JavaScript

Although JavaScript as a program language is appreciated much more than a few years ago, it is still a quirky language. But that’s no problem for Michael: “Yeh, it’s a weird language. But I come from a background of Perl, so I like weird languages! But actually, JavaScript on the server side is a totally refreshing experience. Rhino, for example, allows you to use all the latest cutting-edge JavaScript syntax and features, and you never have to worry about running in an ancient or buggy web browser. I hope and expect that server side JavaScript will really start catching on in the next few years.”

A bit about Michael Mathews

It was hard to find a bit of information about New Yorker Michael Mathews. Although JSDoc has been around for almost 10 years and is downloaded a lot, he hasn’t been interviewed before. He has been asked many times for some assistance though. It can create funny situations: “I was doing some freelance work and the fellow sitting next to me asked if I’d ever heard anything about this ‘JSDoc’ stuff he was trying to use. I said I had heard of it and helped him sort it out. I had to eventually admit that I was the creator of the tool. He seemed a little surprised by that.”

Mathews started as a zookeeper, which he had done for a few years. But it wasn’t that much fun for him. “I basically cleaned up after lots of unusual animals.” When he wasn’t working, he played with his computer. “By the late nineties I was had my own homepage, complete with the large, requisite, ‘Under Construction’ message.” His work behind the computer payed off eventually: “in the fall of 1998 I was employed as a Web Developer for MTV Online, working in Times Square in New York City. It still seems amazing to me.

He now works since 2008 for the BBC in London where he works on the Glow JavaScript library. And yes, everything of it is documented with the help of JSDoc Toolkit.

Glow is a JavaScript library that just, like Prototype and jQuery, makes programming in JavaScript easier. The difference is that Glow supports whatever standard is currently defined by the BBC Standards and Guidelines for browsers, accessibility and usability. This could mean it has to support older browsers that other major JavaScript libraries have already dropped.

Links

• JSDoc Toolkit
• JSDoc Toolkit Twitter
• JSDoc Toolkit 3 Blog
• JsDoc Toolkit Users Group

Related posts:

1. Codeview, a new template for JSDoc Toolkit