I am working with an undocumented, 100.000 lines Delphi 7 project and one of my goals is to create a software architecture document from the source code.
Can you give me any ideas on how to approach this?
These tools work with Delphi 7 and are of great help:
the UML tool ModelMaker
the refacotoring tool ModelMaker Code Explorer
the documentation tool Documentation Insight (as of august 2012)
UML diagrams are a great way to get an overview of structure. How well that overview is, depends on how well the structure is.
For taking over projects like these, I start with some basic documentation (often in MarkDown format, as that text based format is version control friendly, and generates nice HTML).
To get that going, it helps if the original developers or/and some base documentation are still there.
Then just start to:
fix bugs / apply feature requests
use ModelMaker to get a feel for overall structure
use ModelMaker Code Explorer as a refactoring tool
use Documentation Insight to document inside the source code (you can generate help files and web pages with the pro version, see feature matrix)
update my Markdown documents with any information that does not fit in the source code documentation well
Note you can put some documentation in using Model Maker Code Explorer, but it can not be exported as help files, since it uses a different documentation format than Documentation Insight.
So I agree with the comment by Jan Doggen (thanks Jan!): just start. Make sure you have the right tools to help that going.
Try running the source code through a newer Delphi version that supports UML modeling, then let it show you how different sections of code related to each other.
Understand will do the job. Free download includes 15 days evaluation which will be more then enough for what you need to document.
Related
Er...is there documentation for turbopower's OnGuard anywhere?
Finally got the source code to turn itself into components on the pallete (D2009) and can run the examples but I don't know what most of the components do or which I need.
There used to be documentation when it was a commercial product. Does it still exist?
Howard
Ah, I'd been looking for two days and eventually found the documentation five minutes after posting this message. To save anyone else the trouble they are here
http://sourceforge.net/projects/tponguard/files/tponguard_docs/1.13/
The documentation is still available on SourceForge, along with the source code.
Update: Most of the TurboPower components are being maintained as part of TurboPack, a collection of open source tools being kept up to date by Roman Kassebaum. The most recent versions of the source code and documentation for OnGuard are on GitHub.
For two examples on how to use the OnGuard library look at this question.
The two approaches there are roughly equivalent, Runner's answer creates the OnGuard components at runtime, while my answer uses the procedural OnGuard API and has slightly less overhead as a result.
There is a third approach of dropping the components on a form directly rather than creating them at runtime. There's nothing particularly wrong with doing this, I've just found it unnecessary and not really saving anything more than a line or two of code.
I am looking for a tool to generate Delphi source code documentation, and I want to give a try to Doc-O-Matic Express (which is free). Are there any guidelines for beginners how to use Doc-O-Matic Express to document Delphi source code (managing doc-o-matic projects, preferred docblock style, complete docblock syntax, etc) ?
Don't bother with Doc-o-matic settings right now. The express edition is command-line only.
Choose a comment style
Comment your code
Generate documentation (a default project is enough to start)
Verify you comment coverage
Doc-o-matic support JavaDoc and XMLDoc (or even kind-of native comments). The tool it-self will help only if your code is already comment, or if you want to comment directly inside its IDE.
If you like XML Doc or JavaDoc,
Doc-O-Matic does support both equally
well and all three styles are
supported when writing source comments
through the integrated editor back to
the source.
In this page you can found a doc which can be useful for you Delphi Documentation Guidelines. I used this guidelines to document my source code in this project.
I am seeking to understand someone else's code in Delphi 7 (I suspect that newer version have this built in, but I don't want to spring > $1k for the newest version).
Are their any (preferably FOSS) tools which will help me generate a class hierarchy diagram?
Actually, the class browser in GExperts is ok. Maybe not as good as the accepted answer, but just one of a great collection of tools
You can use ESS-model from SourceForge.
If you Load and .PAS (also .DPR, .CLASS,...) with some classes this program generate a Class Diagram and some Documentation. It's free and you can access to code source.
Regards
AFAIK ModelMaker 6.2 was included with Delphi 7, it's a UML tool. You can import your source code in it and generate class diagrams etc, I really don't remember anymore all of it's features, but I do remember that ModelMaker is awesome tool and it's sure worth a look.
Update: Model Maker (now MMX) is now free for all supported Delphi IDEs
You can take a look at our SynProject tool.
Synopse SynProject is an open source application for code source versioning and automated documentation of Delphi projects.
There is a pascal source parser, which will create all classes hierarchy documentation.
And it's much more than a parser: you can write the whole Specifications/Architecture/Design/Test/Release documents list in an integrated manner.
There are some tutorials, screenshots and resulting documentation sample in the above link.
Peganza's Pascal Analyzer (not FOSS)
Doc-o-matic's documentation generator creates class hierarchies. They have a free express version you can try.
If you have been successful in persisting your data, which type of stream did you get to work
Text or Binary
ANSI or UNICODE
Did you have to use any BOOST_ASSERTS or some extra MACRO or dance around the fairy ring at 4:00 am wearing your Moose sweater backwards.
Thanks for your answer
There is a posting for C++Builder 2010 (unfortunately I do not know of one for 2009), that shows the portions of the Boost (1.39) that are included in the shipping product. The serialization library is listed as not supported. Note the posting also includes a link to the source code they used in case someone wants to experiment with the unsupported libraries.
I haven't tried, so I can't directly answer. However, here are the boost 1.37.0 test results for C++Builder 2009 (the column on the right, "borland-6.1.0").
You can see most things in 'serialization' pass the tests. Some don't, so if you compare what you're trying to do to those it should help you to know what to avoid. The test suites may also useful to you, because they can be used as code examples for using the features they test.
You may find other resources on the C++ Builder Boost page to be useful too.
Are there any support tools like coderush or resharper for F#?
Preview version of FSharpRefactor released in Visual Studio Gallery.
http://visualstudiogallery.msdn.microsoft.com/339cbae9-911d-4f99-9033-3c3564676f45
http://www.youtube.com/watch?v=T6-YjUULNCA/
F# Refactor open source project on CodePlex (Apache license).
Take a look at the open-source Visual F# Power Tools project. They've got a rename refactoring, some code generation stuff (eg. record stub generation), graying out of unused declarations, as well as some other things. They're moving pretty fast at the moment, with lots of new features getting added all the time.
There's an effort to support F# in ReSharper via an external plug-in (itself written in F#). You can find preliminary info here.
FSharpRefactor 0.1 (Preview version) Released on the Visual Studio Gallery.
http://visualstudiogallery.msdn.microsoft.com/339cbae9-911d-4f99-9033-3c3564676f45?SRC=Home
Not yet, as far as I know. I was also looking for something similar to no success. I suspect as soon as F# hits VS2010 as its integral part, or even a bit earlier, such tools will eventually emerge.
As far as ReSharper is concerned, you may want to drop JetBrains a quick email, it would be interesting to know whether these guys have any plans regarding F#.
Since the push in f# is towards light mode the reformatting possible is likely to be both limited, and hard to implement.
Normally reformatting takes the structural information and uses that to create the textual position. In the case of #light the textual position (of indenting at least) is the structure. As such any reformatting would be at best to sort inter symbol spacing, hardly onerous to do yourself.
I would therefore not expect a commercial product for it at least until the 'proper' integration with the IDE (I do not consider the current CTP proper in this regard since several outstanding bugs with it exist which will not be fixed in 2008)
CodeRush is working in F# editor. At least some code assistance and code templates. But code templates are not defined yet (you have to create your own).