Writing XML docs for JavaScript

One of the really nice thing about self-documenting code came from (as far as I'm aware, although they probably borrowed it from elsewhere) Java's javadoc.  In .NET this was again borrowed.

I've read a few articles recently about VS.NET 2008 inferring javascript 'doc' from javascript code, and it got me thinking.

At the end, the purpose of self-documenting code is so that fellow developers (most likely your colleagues working late or a maintainer a few years later) don't have to second-guess what a method is doing.  And you really don't want them to be calling you at 11pm in the evening.  It stuffs you up for the evening and it makes you guilty that they are still at work that late.

There are two links I've read that talks in detail how intellisense for javascript is produced from reading javascript.  I'll link them below.

http://weblogs.asp.net/scottgu/archive/2007/06/21/vs-2008-javascript-intellisense.aspx

http://weblogs.asp.net/bleroy/archive/2007/04/23/the-format-for-javascript-doc-comments.aspx 

Both are very fascinating.  Ideally javascript libraries like JQuery or Prototype (and others) should implement code commenting, as they ship with a compressed version anyway that has all the commenting stripped.

Perhaps it's possible to 'inject' code comments into jquery source code from their online API:

1. download latest jQuery.Uncompressed
2. grab a copy of the jQuery API
3. for each function in jQuery js - following the rules from bleroy above, insert API
4. happy jQuery intellisense in VS.NET 2008 :-)
5. commit to internal source control
6. repeat process for each new version of jQuery

jliu

C# Generic TryParse Extension method

public static T? TryParse<T>(this object obj) where T : struct
{
if (obj == null) return null;

T? result = null;
TypeConverter converter = TypeDescriptor.GetConverter(typeof(T));
if (converter != null)
{
try
{
           // result = (T)converter.ConvertFrom(obj);
           string str = obj.ToString(); 
           result = (T)converter.ConvertFromString(str);
}
catch (Exception)
{
}
}
return result;
}

To use this baby:

decimal? d = obj.TryParse<decimal>();
int? i = obj.TryParse<int>();
DateTime? dt = obj.TryParse<DateTime>();

object = null.TryParse<string>();

here's some more craziness...

public static T? TryParse<T>(this object obj, Func<Exception, T?> repairFunc) where T : struct
// repairFunc to handle what happens during an exception.

Source code merge program

A good source code merge program is different from a basic text merge program.  A source code merge program needs to understand that it is computer code it's merging.

This affects how the merge program's behaviour when it comes to:

• Code blocks
• comment blocks
• Refactoring
• File headers
• Indentation
• Matching brackets }

jliu

The funkiness that is LINQ.Contains

Ok, I'm running into brick walls.

I'm trying to do this:

from p in Products
join i in new[] {1,2,3}
on p.Id equals i
select p

I get

NotSupportedException 
Local sequence cannot be used in LINQ to SQL implementation of query operators except the Contains() operator.

I try again with this:

from p in Products
where ( new[] {1,2,3}).Contains (p.Id )
select p

Woot got some data back in LinqPad.

Tried this in actual code...

IList<int> ids = new List<int>(new[] {1, 2, 3});
IQueryable<Product> product =
from p in Products
where ids.Contains(p.Id)
select p;

I get

Method 'Boolean Contains(Int32)' has no supported translation to SQL.

But it just worked in LinqPad...

Try again:

IEnumerable<int> ids = new int[] {1, 2, 3};
IQueryable<Product> product =
from p in Products
where ids.Contains(p.Id)
select p;

Bingo.

So summary:

In LINQ, IEnumerable.Contains is only implemented for the IEnumerable interface and not the IList interface.  Seems obvious now in hindsight.

Keeping the data in the database clean

On this new project we've designed a database from the ground up.  And we've done a lot of interesting design in the system, such as implementing one-to-one tables that mirror domain object inheritance in the actual system, and referencing a number of lookup tables.

There are no real data yet, so when we need to test something, it goes into the dev database pretty much via someone running an insert script.

Inevitably, we end up with bad data, data that doesn't match the design of the database, and don't show up on views that joins multiple tables.

In this area I've come to appreciate what my old company did.  They had heaps of views designed to catch bad data.

There's always a tiny part of my soul that says... but if you designed the database with proper constraints in the first place, you'd never have bad data in the first place.

May be our database constraints are too weak, but I suspect it's because we wanted the flexibility to define our data, and some of these flexible definitions can't be protected adequately with database constraints.

jliu