Javadoc Clutter

Ed Gibbs, one of my favorite bloggers, writes on the usefulness of javadoc comments. (I meant to write on Alfred Thompson's thoughts on the issue last month as well, but didn't get to it.) Here's my take: If you're coding properly, you have lots of little methods, as Ed says, and they should be just about self-documenting and not really in need of comments. But, when you have code organized like this, it becomes even more important that the big picture be kept in mind somewhere. This partly means working on good class-level documentation - how the class is intended to be used for example, but it also means having good diagrams of the entire application. With this, you may realize not only how the class is intended to be used, but how it's being used in an unintended way, or how it's duplicating the functionality of this other class over here and they need to be merged into a single class.

So where do the diagrams come from? As Alfred mentions, you can use class designers like the one in Visual Studio, but my feeling is that that is only a starting point. There are so many different diagrams you can make: dataflow, inheritance, etc., but you have to keep in mind that the point of any diagram is to help the reader grok the system. What I like to do is keep a documentation wiki around, and generate some diagrams that can be added as pictures, and as a starting point for some user-defined text to help explain them.

But when you do that, eventually you're going to want hyperlinks in the text that lead back to the class, and its description, and its methods. And this is where Javadoc comes in. In the build, throw in a step that generates HTML pages from the Javadocs, and make them available to the users of the project wiki. I think this gives you the nicest combination of high-level overviews and class-level references, both of which are essential to a well-managed project.

The 20 Dumbest Words in Software Development

Brandon McMillon writes on doing it right. (Thanks to Alfred Thompson for the link.) He doesn't touch on the agile side of software development - although I can guess his opinion by his planned article "Pair Programming is for Morons" - and so the article has a lot of stuff about Objectives and Requirements and Spending Design Time Up Front. The tricky bit about commenting on this sort of article is that I don't really disagree; his straw man comparison is that one group who just goes off and starts coding so they can get it done faster. That is bad. He does mention how getting sign-off and buy-in from users and stakeholders is valuable, and here's where we might differ: getting this sort of data is important throughout the life of the project, not just somewhere near the front. Because once a user gets some working software in his her hands, she's immediately going to have ideas to improve it, and they'll probably be good ones. So, while it's nice to do some designing up front, it's more important to have your code in a state where you can make changes easily and quickly, to respond to the inevitably changing user requirements.

What I have written here is short, and therefore oversimplifies the many issues. But the full range of agile practices can answer most objections, in my experience.

Should Newspapers Become Local Blog Networks?

Scott Karp at Publishing 2.0 writes about newspapers jacking up their blog count. I think the thing that most people are missing when it comes to whether newspapers should be more like blogs, or should bloggers be more like reporters, is that we, as blog readers, are really, really interested in who's writing the story we're reading. It's why there are columnists. After a while, people would read anything Dave Barry wrote because, as soon as they saw his name on the column, they knew they were in for a funny article.

But it's the same thing with real news. Our local paper just had a bunch of articles on the competence of the county auditor, many written by a reporter named James Boyd. They're good, if controversial, articles, and ended with the online version having dozens of comments along the lines of, "the real story is...", "what the paper needs to do is...", "why on earth didn't they report on...", and finally Mr. Boyd, possibly tired of all this, chimed in with his side of the story and explained just why he reported on what he did, and what kind of feedback he got from the auditor. The comments immediately became much nicer.

Why? Because people then realized they weren't just trashing a corporation, they were trashing a real person, and one willing and able to defend his actions. It created a conversation rather than a soapbox. So, even though Mr. Boyd is a reporter, I think what I'd really like to see on the site is his pseudo-blog: maybe nothing more than a list (with, of course, RSS feed) of all the stories he writes. When we know who's on the other side of the pen, the story becomes a lot more interesting.

Learning from Joel Spolsky (and Dave Winer)

Here are my comments on Joel's comments on Dave Winer's comments concerning comments. I think Dave is dead-on, but the whole issue is really more of an A-List issue than it is a general concern. I bet there's some sort of law that states that the amount of garbage increases exponentially to the number of participants; if there isn't, there should be. If you have a small blog where just a few people comment - or none, like this one - the quality of the discourse tends to be pretty high, but when you start having thousands of readers, the number of people who have their own agenda to push starts to outweigh the number with interesting feedback. I have comments enabled, and I expect to have them for the foreseeable future :)

But I still want some way to do trackbacks. I don't think the existing trackback system is able stop spam well enough to be useful, but the fact is, no one who reads Joel's post will ever find out about this one, as far as I can see; especially the casual reader who only stops by for a few seconds.

Jobs of the future, #1: Online Community Organizer

Seth Godin suggests that an up-and-coming job description will be Online Community Organizer; that would be someone who can gather together everyone in an industry and make them feel like they have to be part of the conversation in this forum. I could see it coming someday, but my feeling right now is that all of the successful online communities are happening more or less by accident. Facebook, MySpace, Twitter. What makes Twitter a more dynamic online community than Pownce? Not much, I hear; maybe some sort of first- or second-mover advantage? But is there really somebody out there capable of moving from one job of this type to another and being successful at both? I have my doubts.

Marc Andreessen's Eleven lessons

Marc's disabled comments on his (excellent) blog. Marc, I see at least two issues with that: First, a lot of times I only have a sentence or two to add to a post and it hardly seems worthwhile to create a brand new article on my own blog. Second, if anything it's even easier to spam trackbacks than it is comments! Although I don't have enough readers to bother about any spam-blocking besides the Blogger default captcha, surely you could come up with some mechanism to ensure a human is the one entering the comment. And isn't it a shame to restrict comments only to those who have their own websites?

Evaluating Javascript in an NUnit test

Adam Esterline posted his solution to javascript testing. He uses WatiN to run tests, which I wasn't excited about; I was hoping for a way to test where I didn't have to install any more software anywhere. Here's the solution I came up with:

static object Evaluator(string code )
{

ICodeCompiler compiler;

compiler = new JScriptCodeProvider().CreateCompiler();
CompilerParameters parameters;

parameters = new CompilerParameters();
parameters.GenerateInMemory = true;
parameters.GenerateExecutable = true;

parameters.ReferencedAssemblies.Add(Assembly.GetExecutingAssembly().Location);

CompilerResults results;

results = compiler.CompileAssemblyFromSource(parameters, code);
if (results.Errors.Count > 0)
     throw new Exception(results.Errors[0 ].ErrorText);

Assembly assembly = results.CompiledAssembly;

MethodInfo entryPoint = assembly.EntryPoint;

return entryPoint.Invoke(null, new object[] { null } );

}

[Test]
public void EvaluatorTest()
{
  Evaluator( "Context.Current.Data = \"Craig\"" );
  Assert.AreEqual( "Craig", Context.Current.Data );
}

This seems elegant and able to handle a lot of things like side effects. Unfortunately I've been back on the server side for the most part and haven't really tried to put this code through its paces.