Aldo Bucchi wrote:
Hi,
On Thu, Sep 24, 2009 at 2:03 PM, Kingsley Idehen <kide...@openlinksw.com> wrote:
Aldo Bucchi wrote:
Ivan, Hugh,
Thank you for the pointers.
I have read the docs and in particular found some nice code in ( parts
of ) the Virtuoso Opensource project which I will aim to use as guide.
In general, I find that the language is so powerful ( PL + SPASQL )
that not having a coding style is dangerous.
But peer refactorings can help here.
Some points
* I really miss the shorthand addition in place i.e. myVar :=+ 5
** Lots of string concatenations are flying around in the codebase,
and they look like this
myVar := myVar || 'postfix'
* What's the criteria to use DB.DBA.procedureName or procedureName?
Does the latter resolve to the former qualified name or does it depend
on the user? I see a lot of code writen in the DB.DBA.* catalog, then
I see lots of procedures with no qualification and I also see some
places where they are qualified.
The obsessive compulsive side of me can't get my mind around this ;)
This is a nice one:
* Most procedures have an extensive list of parameters that need to be
documented ( in my code at least ). Since there is no current doc
parser, generator, etc, what if we use a modified inline TTL dialect
to declare metadata for procedures? Comments, links to documentation,
author metadata, etc.
Since the source text is stored on the database itself, then it can be
easy to extract this using a sponger and saving it onto a graph, etc.
Building on the latter suggestion, here's an example.
The idea is that each line in the code becomes a potential subject (
for an SPO;PO;PO,O, etc. statement ).
create procedure foo(
in name varchar, -->> "Name of the person"; rdfs:seeAlso foaf:name .
in lastname varchar -->> rdfs:label "Last Name"; rdfs:seeAlso
foaf:lastName .
) returns varchar
{
}
Common cases can be abbreviated: L stands for rdfs:label
in name varchar, -->> L Name of the person
And this can be put anywhere in the code, the subject will always be
the latter statement.
http( 'I am calling this function with stupid args', 5, 6 );
-->> virt:todo "Fix this!"; foaf:maker ols:johhny ; moat:
This can be useful in the eventuality of creating an IDE. Procedure
documentation gets parsed and stored along with the code and ( some
form of the ) parse tree into an RDF graph ;)
>From there, generating docs can be a piece of cake.
This is just a top of the head proposal. Take it with a grain of salt.
( But I DO want it very badly! )
One more thing.
Since procedures live as isolated enities in the database, we have an
advantage over traditional IDEs. Depending on the granularity of the
parse tree and the metadata ( these comments ), you can achieve pretty
incredible usability feats.
You start the coding experience with a faceted browser over your
procedures. You can type and search a la spotlight, or filter by
author, or look for tags, etc.
And then we fall into full integration with SVN if you want to
roundtrip... but, wait! Virtuoso is WebDAV server! LOL.
Regards,
A
Quick FYI.
You know our entire docbook based docs exist in a Linked Data Graph?
Basically RDF Views over the Docs.
Coming from you, it can't be any other way... ;)
All being well, you should be able to dereference structured descriptions of
every document section, ditto tutorials.
The docs can be beautified via code driven automation if anyone is
interested. We are strict dog-fooders at every level :-)
But what about the previous step. Generating the docs?
You do this by hand?
No, its also automated.
The Function Reference section, for example?
I find my codebase growing and growing, and since there is no Classes
( save for UDT and modules ) to organize code, things become complex
quickly.
If you could also bring the parse tree plus annotations to the RDF
world, then the game can get really interesting.
Phased implementation N1:
* Give each procedure a URI ( based on its name, and URIQA of the
server or general URIQA if they are built in )
* Start with the parameter level annotations ( not more than what
Javadoc gives you )
* Create a simple built-in webapp that provides a UI for this.
That's already a killer feature. I see lots of linking happening.
Yes, but don't know when we'll get to this though :-)
Kingsley
Regards,
A
Kingsley
On Thu, Sep 24, 2009 at 12:54 PM, Ivan Mikhailov
<imikhai...@openlinksw.com> wrote:
Hello Aldo,
On Thu, 2009-09-24 at 01:18 -0400, Aldo Bucchi wrote:
Hi,
1.
I'm looking for Virtuoso programming best practices. Looking at a
codebase like ODS I can see several intermixed styles. Any particular
corpus that you would say is "worth following"?
( other than your own code :P )
My own code is definitely bad example. Every time I write really
interesting and compact and useful procedure I get a request to rewrite
it as C code for better speed and to place into the executable.
2.
Any documentation pattern for procedures? Any tool to generate docs?
I use Doxygen ( http://www.stack.nl/~dimitri/doxygen/ ) notation for
some parts of the C code. It's quite similar to javadoc (it can even
parse javadoc comments). No specific tools or notations are used for
SQL, and there are no strict plans, but I guess I'll extend Doxygen
sooner or later to support SQL sources. ("later" is more probable: I
intend to do that at least twice a year since 2001, still no progress)
Best Regards,
Ivan Mikhailov
OpenLink software
http://virtuoso.openlinksw.com
--
Regards,
Kingsley Idehen Weblog: http://www.openlinksw.com/blog/~kidehen
President & CEO OpenLink Software Web: http://www.openlinksw.com
--
Regards,
Kingsley Idehen Weblog: http://www.openlinksw.com/blog/~kidehen
President & CEO
OpenLink Software Web: http://www.openlinksw.com
