I've recently stumbled across this (http://www.jibbering.com/faq/faq_notes/closures.html) article. It covers (in-depth) JavaScript closures, what they are and how to use them correctly. I wish I would've read this article about half a year ago. It would've saved me a lot of frustration and time spent experimenting.

I'm often using closures in my classes to emulate private members. They can be very powerful allies and are probably one of the main reasons why JavaScript is so dynamic. At the same time they can be quite treacherous and lead to the resource waste, especially in IE with it's memory leak problems. In general I prefer to keep closure use to the minimum.

Here's another good article on closure in global scope.

I decided to switch to jEdit. It's a good free code editor that provides many features VistualStudio is lacking in respect to JavaScript editing. VisualStudio is a wonderful development application. It's very powerful, but it was developed mostly to work with "major" languages (developed or supported by Microsoft - C++, C#, VB). It's pretty good when it comes to working with markup languages (HTML, XML, etc). When it comes to JavaScript, however, some of the features it provides are quite advanced (such as IntelliSense for some DOM objects), while others leave a lot to be desired for (region support, better parsing capabilities, etc.)

I found jEdit some time ago, but today in my frustration with VisualStudio I decided to give it a try and I don't think I can go back to VS now. jEdit has a lot of plug-ins, many of which can be used to support particular style of programming. Often regular expressions are used for configuration. This means it's possible to improve JavaScript editing just by writing appropriate expressions. I started off by adding region support to the script files I edit and it simplified working with them tremendously. In the next couple of days I will play around and see if I can squeeze out some more juice out of jEdit. Hopefully it will not disappoint me.

P.S. I'm still using VS for debugging. It provides the best JavaScript debugger I've seen.

I've been working on adding documentation to Monorail and a thought has crossed my mind. When I'm writing documentation for each method I'm forced to do code review to understand how it works. That's interesting because code review is generally considered a good practice and often many bugs can be fixed early with it. Essentially having to write documentation after writing the method makes code review automatic.

Like a lot of people I'm pretty reluctant to do something I feel is redundant. Often I feel that way about doing code review. I understand it's benefits, but code often looks simple and I become too confident that it is correct (until debugging starts). At the same time I learned to appreciate good documentation and I try keep all my code well documented. Sure it's more work to write documentation, but figuring out how something is supposed to work a year (or a week) from now is even more work.

I'm happy to do code review to write documentation, but... There's always a but. It's usually very beneficial to write at least some of it for the method prior to developing it (what the method does and possibly how it does it) to produce better code. So I need to write documentation before writing the method to have better code and I would like to do it after the method so I wouldn't have to do code review by forcing myself.

One solution is to have only part of the documentation done prior to coding. I.e. describe code function, inputs and outputs, write code, and follow up by preparing examples on how to use the method and how it works. Another solution would be to have method explained in the design document and add documentation to the code after completing the method. In the second approach the code is written in the context of the design document and code documentation is written in the context of the actual code. I'm going to try both approaches and once I figure out which one works better (for me) I will write about it. I might even come up with another alternative.

I've added some support for code samples highlight in the posts. I use CSS so any highlighting is only visible on the web page of the blog. I would really like to make automatic it in RSS and Atom feeds, but I'm not yet sure how to do it correctly.

One solution would be to add link to the CSS with rules on highlighting. I'm not very fond of this solution as the blog client application would attempt to access the webpage to get CSS file and there might be no Internet connection available. Another solution would be to embed current rules into the post when RSS or Atom XML is generated. In either case I need to modify XML generation process and that might be tricky. I will look into doing it sometime soon, but to be truthful I'm not 100% sure I will be able to implement it. In that case I will need to find another solution (like falling back to <code> and <pre> tags instead of using classes).

Above paragraph has an example of the inline code (inline code is just bold). Bellow is example of a code block. It's the CSS code I use for highlighting.

I got to work a little bit on the Castle and I decided to concentrate on writing documentation. The Castle is really a good project and it’s a shame it's unpopular because it’s documentation is lacking. It’s design is so intuitive that in most cases once you understand the idea you won’t have to go back to documentation often.

nAnt is used by the Castle developers to build it. So I started off by adding tasks to generate documentation for all of the Castle sub-projects. The end result I wanted was a single CHM file with documentation for all assemblies. Simple, I thought, but I found out it’s harder than it looks. This brings me to the today’s post topic (finally, after 2 paragraphs, but I feel it’s appropriate to supply some background).

nAnt has a special task (task is one step in a build process) which uses nDoc to generate documentation from XML comments.

I thought I could just configure the task to iterate through all “bin” directories (all projects build into “bin” sub-folder of project’s folder). Iteration works OK, but it goes through all folders (those matching and not matching the pattern). In addition it also goes through all “.svn” folders (used by Subversion for source control) which practically doubles the number of folders nAnt traverses. According to documentation nAnt should've excluded “.svn” folders from traversal, but in this case it didn’t… I’m not sure why.

Another problem is that I only want to document actual release assemblies and ignore test assemblies (with “Tests” somewhere in the assembly name). nAnt decided to ignore my exclude pattern and just included everything.

The solution I came up with is to copy all assemblies to be documented to a separate folder. I hard-coded project folder names (yes, hard-coding is bad, but I could not find a way around it) and the process of selecting assemblies is very quick now. It still takes around 5 minutes on my computer to generate all documentation. There are more than 8000 class members to create HTML pages for, but it’s much faster than before.

Next phase is to add members’ documentation and examples to the code. I’m planning to start with Monorail and move on slowly. Mostly I aim for quality and not quantity. I don't want to go back often to redo it.