Things to improve

Sep 26, 2011 at 8:49 PM

On the positive side, thanks to Onpoint On Demand for a valuable contribution to the open source community. 

On the down side...

Tutorial

I worked through the First Look at Fluent JDF tutorial.  If the intent was to amaze, it succeeded.  If the intent was to explain, it failed.

I can't run Nuget, so I downloaded the FluentJDF binaries, created a new project in VS2010, and started copying in code from the tutorial.  Run.  Crash.  A NullReferenceException from somewhere deep in FluentJDF.  Ok, I need source code to track this down.  (see the following sections for more on this)

Finally got the source to build, and tracked the error down to get_Settings().  I had failed to initialized the settings. An informative exception at this point would be useful for diagnosing this common fault.  Note that the tutorial (the html, not the example file) does not give a complete example of initializing the settings.  It should either show that, or predict failure if one doesn't use the Nuget/Linqpad approach.

The tutorial boasts how much can be accomplished in one line of code, which seems a poor measure when using method chaining, where lines may be arbitrarily long.

If the tutorial intends to lead to understanding, the pace needs to be about half what it is, and explain what each method call does.

What was the philosophy used in this fluent implementation?

Show a non-fluent implementation for comparison.

How does one crawl back up the XML ancestry to add new elements?

Explain Builders vs XmlNodes and document navigation.

Provide an example of how you might parse the document created.

Third-party assemblies:  I found it difficult to locate all the required third-party assemblies.  Due to regressive IT policies, I'm stuck in XP SP2, which Nuget doesn't support.  So I spent a whole afternoon tracking down: 

- Castle

- ExpectedObjects

- Infrastructure

- Machine.Specifications

- Nlog

- NUnit

- Rhino.mocks

- Caliburn.Micro

and building them all so I'd have compatible versions.  Actually, since our IT blocks private websites, I was unable to get Rhino.Mocks, but I commented out the four places it was used.  Which made me wonder if rhino.mocks was really all that necessary to begin with.

Every third-party assembly used provides some value, but multiplies the number of dependencies, effort to configure, learn, and deploy, and sometimes I don't think they're worth it.  Especially in a project where you want others to participate.

Unit Tests

I read unit tests as models of how to use code.   Except that these unit tests had no resemblance to any code I might want to write.  I wasn't sure for a while that it was even C#.   IMHO, the syntactic sugar of ExpectedObjects isn't worth it.

After tracking down most of the required assemblies for the unit tests, I discovered I still needed to re-educate Resharper to recognize the unit tests.  I just gave up on the unit tests at that point.

BTW I despise K&R braces.

FluentJDF

The code at times seems a little too fluent.  Methods are added whose purpose is to simply combine two other methods.  For example,

public JdfNodeBuilder AddIntent() {
     return ParentJdfNode.AddIntent();
}

While this reduces the amount of program code, it also hides informations (such as the fact that we're now operating on the parent node), so it increases the amount of knowledge needed to understand the code.  Admittedly, one doesn't have to use those functions.  If prefer a sparser library which may lead to writing a little more code, but forces revealing (rather than hiding) the structure of the XDocument we're building.

Roadmap

After becoming more familiar with the code, it was evident that it was all about writing JDF files and messaging, and there was no methods for building Controllers, Queues, or workflow, all the integration stuff that one needs to build a complete JDF system.   Its worth pointing out upfront that that functionality is in a for-sale product.  It also raises the question of whether FluentJDF might grow in that direction.

Documentation

API-level documentation is provided, and it is admittedly thin.  Specific topics to cover:

- high-level documentation that explains the design behind this implementation

- where this code is intended to fit into a complete product

- tutorials on specific problems.  eg. editing existing JDF files, custom namespaces

Summary

From what I've seen, and my few tests, FluentJDF seems to work as advertised.  The presence of unit tests (even though I've not gone through the effort to run them) is comforting.  The author(s) seem to have a firm grasp on JDF, so I believe the design is viable.

But FluentJDF by itself is not a complete JDF library, and depending on a plethora of third-party dlls is a barrier to some.

<FlackJacket>On</FlackJacket>

Coordinator
Sep 27, 2011 at 10:38 AM
Edited Sep 27, 2011 at 10:55 AM

As our mission states, Fluent JDF is oriented towards building JDF clients.  Our goal is to make developing .NET clients easier and we have already made significant progress in that area.  We realize the documentation and examples are thin, but that is typical in the early days of any open source effort.   It's early days in the project and there is certainly a long way to go.  

To date we have focused on code and not documentation.  That is pretty typical for open source. We put together the Nuget distribution because it is a good way to make things a little easier for folks with up to date tooling.   We do realize the bootstrap can be tricky and will eventually have more samples, documentation and perhaps even scripts in the Nuget package easier.  For now, you'll have to contribute at least a little elbow grease to put things together for yourself especially if you can't use Nuget.

We believe strongly in using best of breed libraries wherever possible.  That is why we will continue to utilize a plethora of open source libraries.   We tend to stay on the latest release of our open source dependencies.   Our command-line build brings down all the right dependencies even if you don't have the Nuget tooling in VS.NET.   

The beauty of open source is the opportunity to contribute.  You can always fork the code and make a pull request.  We would be happy to accept contributions to the documentation.  We would also be happy to cross-link good blog entries on how to use Fluent JDF.

Internally, we are working on the controller framework, which we call the JDF Workflow Foundation (JWF).  The initial release will include the controller framework and basic message handling.  Things like a signal registry and async messaging support are planned.  This product may become open source but will certainly have a commercial license component.  Usage is free for development and free for small deployments.  We will be announcing more on JWF in the near future.

 

Sep 27, 2011 at 1:38 PM
tcabanski wrote:

"Fluent JDF is oriented towards building JDF clients."

More precisely, FluentJDF is oriented toward building JDF agents.  (Agents in a JDF workflow are responsible for writing JDF.)  Whether the agent (and sending code) is in a client depends on the application. 

I don't fault this project for its youth.  The project needs to grow, and I'm pointing out the growth areas most valuable to me.  BTW, your marketing guy put me up to this. =)

 

Coordinator
Sep 27, 2011 at 2:09 PM

There is no doubt that Fluent JDF could best be described as a library for building JDF Agents.   I got in the habit of using the word "client" here because the term "JDF agent" is not something the average .NET developer new to JDF knows anything about.  Our docs and home page will probably become more educational about JDF in general over time so we can start using the right terminology.   

I certainly appreciate your feedback.