Documenting VFP Projects? 3

[David Higgs]

As a Recreational User of VFP I dip into / out of VFP periodically; maybe not too dissimilar to a Programmer visiting different clients.

One of the issues I have with my aged memory is finding my around my code, remembering where pieces of code are located, List of Procedures, Methods and Variables etc. Like most projects I guess, my projects start off as fairly basic code and then develop as my knowledge base improves enabling me to make further development.

So my question is, how / what should I use to document my projects?

Regards,

David.

Recreational user of VFP.

 

[Mike Lewis]

There's a tool called the Documenting Wizard (Tools -> Wizards) that is moderately useful. Give it a try. It is reasonably self-explanatory.

Mike

__________________________________
Mike Lewis (Edinburgh, Scotland)

Visual FoxPro articles, tips and downloads

 

[tomk3]

Hello,

I like "PDM", see here

http://gorila.netlab.cz/pdm.html

Regards
tom

 

[Mike Lewis]

Of course, the most important documentation tool is your comments within your program code. And the best only way to do comments is to add them as you go along. It might be too late for you to do that within your existing code, but, it you don't already do so, it's something you should definitely do in future.

And not only program code. You can add comments to fields within a database (in the MODIFY STRUCTURE dialogue); to properties and methods in custom classes (in the Edit Property / Method dialogue in the class designer); to menu items (in the Prompt Options dialogue in the menu designer); even to expressions in a report (in Properties -> Other).

Mike

__________________________________
Mike Lewis (Edinburgh, Scotland)

Visual FoxPro articles, tips and downloads

 

[TamarGranor]

Beyond documentation, there are a lot of good tools in VFP, especially in Thor, that help you find your way around your code. Especially, check out GoFish and Finder, which are both VFPX tools that are included in Thor.

Tamar

 

[Koen Piller]

Tamar,

Under which menu item one can find Documentation in Thor?

Rgds,

Koen

 

[David Higgs]

There's a tool called the Documenting Wizard (Tools -> Wizards) that is moderately useful.

I did have a brief look at the Documenting Wizard. I think using the Documentation Wizard combined with your suggestion of adding comments to my code as I go along is sound advice. I have made “comments” in my code where appropriate, explaining what’s happening in each line, but I think I need to make further in-depth comments on code that is called from elsewhere for example.

I like "PDM"

I’ll take a look at PDM, quite a bit to take in.

check out GoFish and Finder, which are both VFPX tools that are included in Thor.

I have GoFish in one of my folders; time to take a look at it again. I will also take a look in VFPX Tools. I do use VFP Code References and understand that GoFish is probably a better Tool to use. To be honest I keep forgetting I have GoFish installed!

Thank you all for your replies.


Regards,

David.

Recreational user of VFP.

 

[TamarGranor]

There's are several documentation tools for tables and databases in the Tables menu. In addition, the Reports menu has a fairly cool tool for cross-references.

However, what I was trying to say and worded badly is that Thor has a bunch of tools that help you, regardless of whether you have documentation.

Tamar

 

[Mike Lewis]

Regarding documentation tools for databases ....

It's true that there are several tools available that will automatically generate documentation from an existing database. Most of us will have used these from time to time - or perhaps written our own.

An alternative approach

I'd like to suggest an alternative approach. Rather than generate the document from the database, my approach is to generate the database from the document. This won't help you if you want to document an existing database. But I would argue that it is the better approach when starting a new project from scratch. I have used this technique on three separate projects now - with satisfactory results.

With this approach, you create a document (probably in Microsoft Word) which fully describes the database: the table structures, indexes, field formats, etc. You circulate the document to team members and other interested parties, who then comment on, amend and refine the design. It's obviously easier to do all that while the whole thing is still on paper. Once the design is finalised, you press a button and the database is automatically created (sans data, of course, at this stage).

This is not all that difficult to achieve. A VFP program can use Automation to analyse the Word document. It can then generate a second program which actually creates the database. Since this consists mainly of SQL CREATE TABLE statements, the target database need not be specific to VFP; you could use the same technique to produce a database for SQL Server, MySQL, or whatever.

How to do it

If you like this idea, you are welcome to use the program which I wrote for this. The Word document has to follow a fairly rigid structure, but I explain how to do that in the instructions for using the program. You can find those instructions, along with a download link, here:[link

http://www.ml-consult.co.uk/foxst-42.htm

]

http://www.ml-consult.co.uk/foxst-42.htm

[/url]

Please keep in mind that I wrote this program for my own use, not for a mass market. It has a sparse user interface and very little error-checking. It meets my own requirements, but will need tweaking if your requirements are different. Nevertheless, I hope others will find it useful.

Mike


__________________________________
Mike Lewis (Edinburgh, Scotland)

Visual FoxPro articles, tips and downloads

 

[Olaf Doschke]

All such tools do is give an overview of what components exist, and actually you get no new information than what the PJX gives itself.

What can help bring together condensed information about how things work in your project is having comment headers in each function/procedure of PRGs and method of classes, but that's also not automatic, so indeed I second Mike in pointing out comments are important.

More complex and may be less intuitive components better have extra documentation describing them, so really write out a word document. But indeed the intuitiveness of a library isn't the main reason to do so, complexity'/size, too and an overall overview of components, as documentation should be. It is asked too much of a documenting tool to find the topics/realms of any project and structure documentation the way you can do yourself. Especially in VFP where it is far more usual everything is in one project. In .NET it's much more natural to make several assemblies (DLLs) used as compartments of an overall project, in VFP your DLLs are more like the VCXes and PRGs that encapsulate a set of functions/functionalities.

What no documenting tool can handle for you is giving more insight into the working of your code than you can by such real documentation, what it may do more than what VFPs wizard or PDM does and what I haven't seen done is the automatic extraction of dependencies, who creates and uses which objects, which methods and how and then other metrics like simple the length of methods/functions/procedures can tell you where code may be going against good measures.

One API-project I provided as an APP (really a VFP APP file) was a database interface that became something like a service structure or web service was today, just not centralized in an intranet server, but in VFPs typical client way at the client-side. You created a specific class "interface" via NewObject() specifying the app file and so used it a) without compiling it into your own PJX and b) could update for the same reason without the need to change any other code, as long as changes were made compatible.

In this interface project, I explicitly added a method "documentation" into classes, that was only consisting of comments, describing the whole class, on top of the description in any method header zo have overview documentation.

And a typical header comment section should besides simple information like author/company/date of creation/change contain a method description, tell what the method does, what parameters mean and which are mandatory or optional and give an example.

And on top of that, a test method also was introduced, but that was later put into a separate unit test project running all interface methods with test calls. The topic of database interface made it very testable, too, as that didn't include any forms and user interaction, mainly something that could also have been made as stored procs of a database, but also when data of multiple DBCs and also MSSQL Server databases was involved, so really a centralisation of business logic about the whole database landscape.

The principles also apply to normal projects, though, especially having comment headers. But they don't fall from the sky or are about information in the PJX, VFP will not note which Windo account worked on which code on which date, you don't even get such simple chronologic information from a documentation tool if you don't put it inside comments while you work.

Bye, Olaf.

Olaf Doschke Software Engineering

https://www.doschke.name

 

[Mike Lewis]

In this interface project, I explicitly added a method "documentation" into classes, that was only consisting of comments

I do the same, but in my case I have a Documentation method in each of my low-level base classes. This is an abstract method, in that it is empty at the lowest level, but I can populate it with code as appropriate in subclasses and objects. It means that I can get at the documentation very easily while working in the form- or class-designer. It also lends itself to automatic extraction. And it is self-contained; if you distribute the class to another developer, you don't need to remember to distribute a separate document.

Mike

__________________________________
Mike Lewis (Edinburgh, Scotland)

Visual FoxPro articles, tips and downloads

 

[Olaf Doschke]

The extraction of documentation was an idea I had, too. I didn't go further than pulling together a text by reading out method parameterizations, headers and the documentation methods in the different inheritance levels. It would be nice to create a dependency matrix by parsing source code at least on a simple level finding method names and seeing which classes call which own/inherited methods, but also methods of other classes.

Bye, Olaf.

Olaf Doschke Software Engineering

https://www.doschke.name