Language Specification: Useful? Not?

Random question for people: how many people out there actually ever look at the VB language specification? The original purpose of writing the language specification was purely for internal use, done so we’d have a reasonably authoritative explanation of the language aside from “whatever the compiler does” and “whatever MSDN happens to say.” And to have a place where historical thinking could be preserved for future generations of VB team members, so there’d be some chance in hell that we could avoid making the same mistakes twice. But how useful is it for the public? Not that much, I would imagine, but I’m curious.

There should be a second edition of the 8.0 spec coming out in the next few months. Besides a bunch of corrections, it also cleans up the formatting and also–surprise, surprise–actually ensures that all the examples work and do what the spec says they will do. Up until now, language specifications have been published in Word, but with the new PDF tools that are available for Word, that’s an option too. Do people like the Word format? Would you prefer PDF? Or both?

And finally, how tied are people to the structure of the specification? The Everett and Whidbey specifications only added on but didn’t change the ordering of existing sections. Orcas will likely do the same. But beyond that, I’ve been toying with the idea of restructuring the spec a bit to make it a little clearer and put topics that should go together, together. I’m wondering if that would really throw people, or whether people wouldn’t mind adapting. Not really a short-term issue, but…

20 thoughts on “Language Specification: Useful? Not?

  1. Wesner Moise

    I have looked at it in order to produce a VB parser…. It was extremely helpful in learning about the differences with C#.

    I noticed that you were listed as the sole author of the document.

    Reply
  2. Wesner Moise

    The language specification is indeed useful.

    Either format is fine… PDF/Word. If you have Word, it’s no trouble to get it into PDF, but it’s is good to have the original document.

    The structure of the specification isn’t important for me, but there might be those who would want the section numbering to remain the same, because other documents reference the sections by number.

    Reply
  3. Serge Baranovsky

    Just like Wesner we used language specs for our VB and C# parsers.

    Word would preferred format as it works better when searching/navigating/indexing the electronic copy. Besides Word would make it an "all Microsoft" solution πŸ˜‰

    If you could keep the document structure the same that would be perfect – make it so much easier to identify the changes when enhancing the existing parsers to support Orcas version.

    Reply
  4. David Hogue

    I have found it useful. I learned about all casting (CType, DirectCast, TryCast, etc.) Also, I think the Mono guys were using it to write a compiler.

    Format doesn’t really matter much. I like pdf, but word works. I’d be fine with plain text…

    I’m not tied to the structure at all. The way it is now works. If there is a better structure, go ahead and change it.

    Reply
  5. Cameron Beccario

    The spec grounds the correctness and legitimacy of the language, and so its public presence, whether widely referenced or not, has ripple effects through all documentation and discussion.

    I often use the language spec file as a model of how to correctly use advanced features of Word. πŸ™‚

    Reply
  6. Anthony D. Green

    I’ve read or referred to it several times in part. Basically to write a syntax colorizer. The EBNF is easier to translate into regex. I find the C# spec to be crap by comparison. For some reason I like the convention in the VB spec better. I tried to read the C++/CLI spec but the massiveness of it – my god…

    It’s useful to all the above groups – people who need to reference what VB is and without that spec it’s hard to say that VB is anything. Now if anyone wants to know I can say "read this – it is VB".

    As far as structure I would endorse a logical grouping. I could argue the section numbers needn’t be preserved between versions as references to the spec should be tightly bound to a specific version. Word definitely, we like to think of MS as a fairly self-centered organization. You putting the doc in .pdf form would be as trecherous as using ClarisWorks or hosting your blog on an apache server running php.

    Reply
  7. Rolf Bjarne Kvinge

    I found the specification extremely useful while writing Mono’s vb compiler, though I don’t think many people are using it for this purpose πŸ™‚

    Regarding the format and structure I don’t really care, Word might be somewhat easier to search, but that’s about it.

    Reply
  8. Daniel Grunwald

    I found the specification useful while writing the VB parser for SharpDevelop’s code-completion.

    As I’ll have to update it for VB 9, not restructuring the spec too much would be nice -> then it’s easier to see the tiny changes that otherwise would be discovered much later by our users.

    Reply
  9. Raj Chaudhuri

    I find the specification useful, as a compiler writer and a power VB user.

    I kind of like the current structure, but am open to a new one.

    As to format, I find PDF to be difficult to read onscreen. Word works for me.

    Reply
  10. Roger Jennings

    As Fabrice mentioned, the spec is a great reference for book authors. This will be especially true for me due to the addition of LINQ-related content.

    Word is best for me, although Word+PDF makes sense for the Word-less folks.

    Merry Christmas,

    –rj

    Reply
  11. paulvick

    Thanks for everyone’s comments! Sounds like PDF isn’t that useful, so I won’t worry too much about it. The structure won’t be changing for VB9, so if I make changes for VB 10.0, I’ll check them out ahead of time!

    Reply
  12. Alain Picard

    For us who need to write language analyzers, this stuff is must. No matter how much a book or MSDN covers feature of a language, the Language specification gives us insight into some important low-level details and the various rules for name resolution or visibility, etc.

    Reply
  13. Reinier

    I have occasionally used specs to figure out tricky semantics details concerning the combination of nheritance and interfaces (IA defines IA.m, A implements IA.m with A.m, B inherits from A and overrides B, when exactly does B.m gets invoked).

    I think it’s hard to overestimate how much credibility you gain by having a publically available spec out there and keeping it up to date with the language you actually implement. For several reasons this gives me, as a user, a level of trust in your product that cannot really be obtained in any other way – even when I don’t actually refer to the spec all that much.

    Reply
  14. Uma Maheswaran J

    Hi Paul,

    To parse the construct "Dim Obj As ClassName(Of Integer).ClassName(Of Integer)", "QualifiedIdentifier" rule mentioned in VB 8.0 Language Specification needs a change to include "( Of TypeArgumentList )". In the second version of 8.0 spec, have you made any changes to the QualifiedIdentifier rule?

    Thank You,

    Uma Maheswaran

    Reply
    1. paulvick

      Uma, I don’t have the original spec in front of me, but the TypeName production should include a ConstructedTypeName production with has the "(Of …)" production in it. So it should parse correctly that way. QualifiedIdentifier is more general than that and is used in places where type arguments are not allowed.

      Reply
      1. Uma Maheswaran J

        Hi Paul,

        Thank you very much for your response.

        As per the current specification, TypeName production does not include a ConstructedTypeName production which has the "(Of …)" production in it.

        When I try to post a message to you by using Contact link, following message is displayed: "Your message could not be sent, most likely due to a problem with the mail server". Due to this reason, I have posted my question directly as a feedback.

        Thank you,

        Uma Maheswaran

        Reply

Leave a Reply