thinking-out-loud

minor adjustment to .text db permissions

I noticed after the fact that there are (I think) three additional stored procedures that don't start with "blog_", but rather start with "DNW_" that seems to have to do with blog stats.

Here is a slightly modified version:

use [INSERT YOUR DOT TEXT DBNAME]
go
declare @username varchar(50)
select @username = 'ASPNET' -- or whatever username you run aspnet under
SELECT 'GRANT EXEC ON ' + O.name + ' to ' + @username + '
go' from
sysobjects O where O.type='P' and name like 'blog_%' and OR name like 'DNW_%'

(thanks for pointing out my stupidity, Dave C.)

Some Comments on "Comments on Comments"

My very good friend anon commented on my last post, asking:

What about interface documentation (summary, param, etc.)?

I agree that implementation how-to comments are usually redundant (if appropriate, a single comment that names the algorithm being used is good), but I like interface assumptions documented.

*Unless* I am building a closed source library/framework, product that someone else is going to program against, and I correspondingly need good documentation for the developers, I typically want to go one of two places to understand interface assumptions: either the regression test suite (you have one, right?), or the code itself.

For example, consider the following psuedo-code (psuedo so I don't have to worry about it compiling):

///

/// Assumes the provided DateTime since is within the previous linear year
///

IList GetWhozitsSince(DateTime since)
{
if(new TimeSpan(since, DateTime.Now).TotalDays > 365)
throw new InvalidDateRangeException("expected something else);

return Persistence.FindWhere(typeof(Whozit), "CreateDate > {0}", since);
}

If you have the source, is the really a need for the comment? If it is really unclear, maybe you could try:

IList GetWhozitsSince(DateTime since)
{
EnsureWithinLastLinearYear(since);

// warning: heretical, hypothetical, metadata-based, O/R mapping ahead
return Persistence.FindWhere(typeof(Whozit), "CreateDate > {0}", since);
}

void EnsureWithinLastLinearYear(DateTime since)
{
int DaysPerYear = 365;
if(new TimeSpan(since, DateTime.Now).TotalDays > DaysPerYear)
throw new InvalidDateRangeException("expected something else);
}

Of course that extra method call might really kill your performance, so maybe the comment makes sense.

(
If you watch Saturday Night Live and have ever seen Fred Armisen on the weekend update trying to teach Jimmy Fallon how to deliver a joke, latin-style, imagine his voice on this next part:

"I'm just kidding."
)

I do think it is worth making the point at this point that I am talking about my personal preference and coding style. If my team agrees to a particular granularity for commenting, I am going to stick to it, if only for the esprit de corps. If I am on a distributed development team, and the disconnectedness forces higher ceremony and more verbose documentation (apart from the source code), then I am all Visio and Word. I just prefer face to face communication, tests, and code as the ultimate arbiter of truth. And I still long for the "Hide the comments" option.

Some Comments on Comments

Plenty of people have ranted on this. Sorry for the echo.

I don't like source code comments. Most of the time, they come in one of two flavors: out-of-date or clueless. One of the biggest wishes I have on my list for Visual Studio is a "completely hide comments all of the time" option.

Comments should explain why. Only add comments when it isn't obvious from the code. Granted, the person who wrote the code is usually the least appropriate person to figure what is or isn't obvious about the code they have written. Also, you might have to comment a bit more for closed source libraries and products that require developer documentation. Caveat Lector.

Comments should not explain what or how. Your source code should. Please do me a favor, do yourself a favor, and learn to like reading source code. Personally, if I comment source code, I usually tend to comment the key extensibility points in the architecture using a class comment at the top of the source file. I try hard to avoid most other comments. Of course, you might hate my software because of that, but I don't really care that much.

Unless you are writing a tutorial on how to use a particular language, please don't add comments that explain how the language works. For example,

try
{
crappySoftware.DoSomethingConvolutedAndComplex();
}
catch(Exception e) // Catch all errors
{
}

Thanks! I wasn't aware that that is what would happen!

// return the Foo string
public string Foo
{
get{return foo;}
}

really?

A comment I would really appreciate:

// Look -- this is a *performance critical section.* I know it looks like a serious hack, but great care
// was taken to ensure this would meet such and such automated benchmark that you can run as follows.
// Please ensure you don't f it up.

One thing that particularly peaves me is including open-source or otherwise (read: useless information) licensing information. It isn't that I mind the license being included or the fact that it is open-source. I love open-source software. I love to read open-source software as a way to learn various techniques or libraries. Please, please, dear open source community, please either start including links to the license or put it at the end of the source file rather than the beginning.

Here is another rant I enjoyed: HelpSourceForgeSuck

WS-MetadataExchange hardly meta

I wish WS-MetadataExchange weren't so hard-wired to Policy, WSDL, Schema. My version of WS-Metadata exchange would be as follows. Feel free to extrapolate from there.

The thing I *don't* like about my suggestion is that when I think about the implementation, of said service, a naive implementation would tend toward switch case or lookup tables, which aren't evil but close. That isn't to say that there isn't a reasonable, clean implementation, but rather that implementations would tend toward less flexible implementations:

show me what you've got

<s12:Envelope
  xmlns:s12='http://www.w3.org/2003/05/soap-envelope'
 xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/03/addressing'
 xmlns:mex='http://schemas.xmlsoap.org/ws/2004/08/jef-mex' >
<s12:Header>
<wsa:Action>http://schemas.xmlsoap.org/ws/2004/08/jef-mex/GetMetaDataList</wsa:Action>
<!-- yada yada -->
</s12:Header>
<s12:Body>
<mex:GetMetaDataList />
</s12:Body>
</s12:Envelope>

a list of what you've got

<s12:Envelope
xmlns:s12='http://www.w3.org/2003/05/soap-envelope'
xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/03/addressing'
xmlns:mex='http://schemas.xmlsoap.org/ws/2004/08/jef-mex' >
<s12:Header>
<wsa:Action>http://schemas.xmlsoap.org/ws/2004/08/jef-mex/MetaDataList</wsa:Action>
<!-- yada yada -->
</s12:Header>
<s12:Body>
<mex:MetaDataList>
<mex:MetaData ns="http://schemas.xmlsoap.org/wsdl/"/>
<mex:MetaData ns="http://http://www.ascc.net/xml/schematron"/>
<mex:MetaData ns="http://http://www.w3.org/2001/XMLSChema"/>
<mex:MetaData ns="http://schemas.xmlsoap.org/ws/2002/12/policy"/>
</mex:MetaDataList>
</s12:Body>
</s12:Envelope>

give this specific one, please

<s12:Envelope
xmlns:s12='http://www.w3.org/2003/05/soap-envelope'
xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/03/addressing'
xmlns:mex='http://schemas.xmlsoap.org/ws/2004/08/jef-mex' >
<s12:Header>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/08/jef-mex/MetaDataRequest
</wsa:Action>
<!-- yada yada -->
</s12:Header>
<s12:Body>
<mex:MetaDataRequest ns="http://schemas.xmlsoap.org/wsdl/"/>
</s12:Body>
</s12:Envelope>

dottext db permissions

I started dorking around with .text tonight for fun, and, all things considered, it was relatively painless. I used the latest binary install, followed the directions, and only ran into one obvious hiccup on the db permissions. I am using windows authentication on the database.

I thought there might be a chance that there was already a "grant exec" script lying around. I saw several recommendations to add grant aspnet dbo access, which I just want to go on the record as saying is a bad idea. A good sql wonk will know this already (I know 'cause I learned from one), but just in case you haven't been exposed, try executing something like

use [INSERT YOUR DOT TEXT DBNAME]
go
declare @username varchar(50)
select @username = 'ASPNET' -- or whatever username you run aspnet under
SELECT 'GRANT EXEC ON ' + O.name + ' to ' + @username + '
go' from
sysobjects O where O.type='P' and name like 'blog_%'

in query analyzer. Output to text, paste to a query window, f5 and viola, good to go.

WSE Pop Quiz Answers

I have been busy enough to not be motivated to blog lately, but I have a backblog of things that I have been thinking about posting on. Please bear with me if some of these end up sounding like ancient history.

In answer to WSE Pop Quiz 2, the problem, as Joseph alludes in the comments, is that the Microsoft.Web.Services2.Addressing.EndpointReference is not easily serializable because it doesn't have a public default constructor, and so you get "issues" when you try to use it. Some alternatives would be to use a string or uri if you only need the uri bits of the EPR, but if you want things like reference properties, you will have to roll your own class. Disappointing, but in the new era of services, you can easily get the impression that code level reuse is considered evil anyhow :).

If you do roll your own, you can obviously use xsd or wsdl to gen the classes, or you can try Christian Weyer's WSContractFirst. I haven't had much luck with imports use wscf, and I want to be able to generate stubs and skeletons form wsdl porttypes OR bindings OR service elements, and I want to be able to target wse and asmx (and wse'd asmx). I would also like to be able to save config options, so that I don't have to type it all into the dialog each time. The new WseWsdl2 in the WSE 2.0 SP1 does a lot of what I want on the proxy side of things, but no dice on the server side.

Since he hasn't held up to his almost promise to open-source the darn thing :), I am rolling my own, partly because I need it now, partly because it is fun. I will open source it when I get it done (please see busy comment from above). Christian, if you are reading this and you are open sourcing it soon, please let me know, because I would hate to waste the effort if I could contribute to your version.

I am borrowing some ideas from Daniel Cazzu's Custom XSD Code Generation MSDN article. He also blogs about the concept and has a follow-on vs.net tool for custom gen. I am personally not a big fan of the inline annotations, though I suppose you could easily add the annotations to a new schema and then import the target schema -- not a terrible tradeoff, all things considered. I have done work with CodeDom for a (gasp, heresy) "transparent", reflective object relational mapper. I, for one, love object-relational mappers, but I hadn't touched the System.Xml.Schema and Serialization classes too much, so it was a great, fun intro. I especially like the reflective types. Just so that you know which side of the fence I land on. More on that later.