BAD Documentation in Code

Hi,

I'm currently wasting my time debugging through the code generated by .nettiers. Is it just me thinking the comments on any element therein aren't of any help at all?

XML comments like:

/// <summary>
/// Gets or sets the PropertyName.
/// </summary>
public string PropertyName …

AREN'T funny!

The code of .nettiers is great and well done, yes... But code on its own is useless if it isn't well documented. As a customer I MUST be able to use .nettiers web controls just from the compiled DLLs, without ANY source code or debugging. I've got my own projects to debug and just want to utilize .nettiers, not getting into it and lose time for my own projects.

Please put a lot more effort in generating well documented code.

Axel Dahmen 

Axel,

What comment would you expect the property to have - it seems perfectly reasonable to me and I would guess there was no intent on humour!

In my opinion the inline code documentation in netTiers is pretty good - sure the online documentation could be better, but this is a community project and if you slate it you are slating yourself. The online documentation is a wiki and so you are welcome to update anything that you think could be better.

As far as your comment "As a customer I MUST be able to use .netTiers web controls just from the compiled DLL's without ANY source code or debugging".  I need to enlighten you on a few points. 

Firstly you are not a customer of .netTiers - as I said before this is a community project and so you maybe a user, but you haven't paid anything for .netTiers. You may be mistaken because .netTiers comes with CodeSmith (and is dependent on it), but it is not a Codesmith product. 

You may also be missing the point with the fact you just want to use the web controls as a dll - you can do that once you've compiled the generated code, but .netTiers is not a binary project. One of the big advantages is that you get all of the source code to use and change as necessary and a proportion of them are specific to your database.  

You will only get out of .netTiers what you are prepared to put in - it's not a commercial product and so admittedly it has some rough edges and documentation could be better, but that is where the community should come in and make it better together - and some people do () and unfortunately a lot don't ().

So instead of complaining please contribute to the benefit of others. 

swin 

Hi swin,

thank you for your response. Please excuse the late reply. I went into Christmas holidays...

From your response I've learned that .netTiers is a community project. And I fully agree with you that it lives from its contributors.

But isn't the intention of the .netTiers project to be used by others? For example, we're using .netTiers in our commercial solution. And we're being paid for our quick contribution to that company solution, but we're not paid for contibuting to the .netTiers project. Personally and privately I'd like to contribute to the .netTiers project, but usually contributing is not the primary goal of any project, but delivering a solution and just using it.

As a user I'm a different target group than a contributor. A user doesn't want to have a look at the source. A user just expects it to run smoothly. XML documentation and IntelliSense is all a user wants to deal with. In the course of a project a user needs to focus on his own source code and on his own goals.

From a user's point of view a comment like the above doesn't give any useful information. It's just repeating the property's name, which is already known and doesn't give any additional information. Thus, it's redundant. A useful comment gives more detailed information about the context (a "property name" like the name of the above property can be virtually anything [as can be seen right from this note]). A useful comment also gives information about what consequences come with setting the property and, optionally, which other properties are related to that property.

As the contributor is virtually the only one who knows all these details when implementing his contribution, he's supposed to be the one to also supply a useful comment. That's part of his contribution and part of the difference between private and public programming style.

In short, my complaint is that a delivery with bad documentation is a useful as US Yellow Pages in Chinese. Great for those who are into Chinese, but most of the users can't use it, altough virtually everything's right at their hands. And I don't think anyone expects US citizens to first learn Chinese before using the Yellow Pages. So no one should expect users to first dig into a third party's source code before using its Assemblies.

Regards,
Axel Dahmen 

 Axel, I agree with you 200%.

I failed to deliever a project, because I used NetTiers (an eairler version). I will never entrust NetTiers to a critical project that my reputation is at stake; I need to make a living an failure is not an option. I think that instead of chasing new features, they should devote the time and effort to a book describing all the features of Nettiers ( Will even help write it). By doing this thay can generate revinue and treat the documentation as a vital component, to the success of NetTiers.

I will continue to play with NetTiers, because I believe one day that it will become a professional product, and will save to a lot of work. Sorry, I am a bit critical, by my reputation and earning a living must come first.

Mike.

P.S. Before, someone comes down on me, When I relized I needed help, I offered to pay, but the NetTiers guys were to busy to take me up on the offer and it was to late when they finialy responded. If this is a comunity, shouldn't the goal of the community be to strive for a better product, or is this this an academic excercise? I offered to help write the docs' but I can't unless I know how to use the tool. I need help with using security, but don't see anthing to help me do it.

Too: Delaware - I am very happy that you know how to use the features that NetTiers Provides, I am not one of the lucky one. If I thought NetTiers was a pile, I would not continue to use it. But, since I am not in school, and have to earn a living: I only have a limited amout of time to figure something out when using NetTiers. 

Actually, I am one of the people here on the forum that is often the harshest on Nettiers. I have several bugs that havent been adequately addressed imho. BUT you guys are giving nettiers a raw deal. I have used it for 2 successful commercial ventures. One of which is an award winning application. Saying that you cannot use nettiers and that it caused you to fail to deliver a product is unrealistic, no matter how you try to spin it. The failure to deliver a product is your own failure. At its core, nettiers is for generating a DAL. thats it, too many people have fallen into the trap of depending on the generated winlibrary or weblibrary to write code for them that they should be comfortable writing themselves. Those other things are a convenience (in my eyes). Nettiers creates DALs very effectively, and in a way that is common sensical. Try using another dal generator, it isnt always pretty.

 Are there problems with Nettiers? Yes.
Should the team stop trying to add new features and fix whats broke?Yes.
Is what is broke preventing applications from being written?No.

Nettiers if for creating DALs. Write your own code.

ecathell,

I disagree.

.netTired ist not just a DAL but is also an intrinsic part of the GUI. Don't forget that it creates DataSourceControls and a couple of GUI controls as well.

Plus, .net Tiers is the interface for a project's business components.

Taking these facts as given, a typical data bound application relies on .netTiers for approximately 60 %!

Now, given that you don't know how to deal with 60 % of your project, how would you estimate the chances of completing your schedule in time?

I don't know how you managed to complete your 2 projects but I don't assume that you had a tight time schedule, right?

It's a fact that when a Software Architect accepts the task of designing a project he's supposed to give both, a time and a budget estimation. Both are ruined by .netTiers non-existing documentation.

.netTiers is not a help, it becomes a blocker once you've agreed on using it in a commercial project.

But I - personally - don't think they should put much more effort into documenting .netTiers any more. .NET 3.5 is now coming up with ADO.NET Entities. It's free as well and assumingly well documented. It will be my favourite for my next project. I'll definitively never use .netTiers again in my live. Too much hassle...

@Mike:
I, too, asked for paid support but didn't get a reply yet. The development team apparently doesn't even want to earn money with the project. I guess this would put them in a position to stand for what they've been doing.

Axel Dahmen 

Fact:

For the past week and a half, I have not been able to use the UI generated by NetTiers, If I try the Designer Locks up. It is NeTTiers related, since I can pull up my own projects or the AjaxControlToolkit and they don't crash,

As far as support, my Joke Strap offers more support.

I had planed to use NetTies, because I thought it would same me time, but the fact is: I have spent more time trying to get it to work; So I for one will not use it for anything other than Rec. Programming. One of the the big features of NetTiers, is that it generates all this stuff for you, but if it doesn't work, how do you gain from it? 

Mike,

As as long as America remains free, that is my opinion!  As I said I am happy that it works for you, it is a let down for me.

Not that it matters, but you both have the same problem. You are relying on nettiers to write your UI code. I write my own UI code. I use Nettiers soley to provide DAL entities. The UI implementation was an afterthought, and provided as a convenience. I dont even think its really modified anymore. If it is, its not by the original author. Like I said, Nettiers Creates a nice 3 tier project, but you really need to write the UI code yourself.

And I dont know what you consider long term vs short term, But our program that won the award was from conception to deployment only a year. Without nettiers, and wrting the DAL by hand, it would have been a lot longer. But we wrote all the UI code by hand. The Business Layer and Data Access Layer were generated(and still are generated) out of Nettiers.

 Nettiers has its issues. But if you use it for what it was designed for, you can work around them pretty easily.

@ Mikew194: Sorry you took my post personally. I was just stating a fact. Nettiers is good for making a DAL and a BLL, write your own UI code. I dont know many generators that do a good job on all three. And I dont know how to put it anyother way.