[dba-VB] Getting TextReader from strings...

<<<
...the XML commenting method I haven't used yet...
>>>
Hi Gustav,

That should be easy for you to adapt I guess:

Download SandCastle:

http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-
A715-696E3A4873B2&displaylang=en 

- start VS2005/VS2008;
- create sample project;
- add some code with XML comments (watch how VS helps to set cross-refs
while you are typing comments - all these crossrefs will be later
"automagically" used by SandCastle while generating online help);
- right-click on project entry in VS solution explorer - select 'Properties'
from popup-menu;
- select [Build] tab;
- check 'Xml documentation file' checkbox;
- (re)build assembly;
- start D:\Program Files\Sandcastle\Examples\generic\SandcastleGui.exe;
- you'll get Sandcastle main form opened;
- make sure presentation style combo-box on the right-hand side is set to
vs2005;
- add assembly file - [Add] button of top listbox;
- add generated comments file .xml (it will be in the same folder where your
assembly is located) - [Add] button of middle listbox;
- click [Build] button in the bottom - SandCastle is a "heavy beast" - it
will take a while for it to generated .chm help even for a small sample
project;
- when Sandcastle build finishes go to D:\Program
Files\Sandcastle\Examples\{YourAssemblyName}\vs2005\chm\{YourAssemblyName}.c
hm and enjoy your professionally looking code help file...

This Help generation can be automated - there are quite some scripts
installed with SandCastle but I haven't used them yet...

SandCastle is a really huge "beast" with many features including preparing
any kind of documentation - see these links:

http://www.codeplex.com/SandcastleStyles 

http://www.codeplex.com/Release/ProjectReleases.aspx?ProjectName=SandcastleS
tyles&ReleaseId=14068 

--
Shamil

-----Original Message-----
From: dba-vb-bounces at databaseadvisors.com
[mailto:dba-vb-bounces at databaseadvisors.com] On Behalf Of Gustav Brock
Sent: Friday, June 27, 2008 1:42 PM
To: dba-vb at databaseadvisors.com
Subject: Re: [dba-VB] Getting TextReader from strings...

Hi Shamil

> I do not argue, OK? :)

OK, that's also how I understood your comments. 

I see your point. There's a big difference between code modules like that of
Rocky's with 2000 lines and a series of small functions and classes where
all variables and methods and properties are given names which clearly
indicate the purpose.

Unfortunately, the XML commenting method I haven't used yet ...

/gustav


>>> shamil at smsconsulting.spb.ru 27-06-2008 11:06 >>>
Hi Gustav,

I do not argue, OK? :)

The point is that inline commenting is becoming less and less
important/useful (and imposes too much costs to be true) as 
nowadays (r-)evolutionary agile Test_Driven-Design (TDD) programming
practices progress: when applied by experienced agilist these practices
result in small max 10-15 code lines "self-explaining" streamlined methods. 

Classes/Modules and Methods DO have XML comments, where the purpose of
classes/modules/methods and all their parameters are described with needed
level of destabilization, as well as additional remarks to explain the
purpose and usage of method in details if needed are supplied but usually no
inline comments in code at all. I have seen somewhere an article from Martin
Fawler or maybe another famous agilist who were "pushing" this approach. And
I do use it and I like it - this is why I write about it :) (IOW I'm not
arguing for the purpose of "pure" arguing but I'm referring to everyday
practices, which I do follow with successfully finished projects and
satisfied customers with some of them being also experienced developers...)

The everyday practice in TDD is that you can "mercilessly refactor" a well
covered by Unit/Integration tests piece of code several times a day, and if
it has inline comments then they become a trouble (they result in additional
significant support costs) as you need to modify them as often as you
refactor your code. But with clean streamlined code every class, interface,
method, parameter is usually self-explaining therefore class level and
method level comments are usually good enough...

Thank you.

--
Shamil

P.S. Very mature IMO article on Agile and XP: "Is Design Dead?" -
http://martinfowler.com/articles/designDead.html 



_______________________________________________
dba-VB mailing list
dba-VB at databaseadvisors.com
http://databaseadvisors.com/mailman/listinfo/dba-vb
http://www.databaseadvisors.com