[x3d-public] X3D Java SAI...compileable examples and uncompileable examples: Vrml2Sourcebook archive rename, naming conventions

[Don Brutzman]

regarding X3D Examples Archive rename Vrml2.0Sourcebook to Vrml2Sourcebook:

On 1/1/2017 6:48 PM, yottzumm at gmail.com wrote:
> No, my revised email is based on renaming the folder.  I can keep renaming the folder with each source checkout (I compile java in my source repository).  I could also generate the java in a separate folder, but I prefer not to.
>
> I think the rename is advisable unless it seriously breaks others’ code (I will have to fix the X3DJSONLD html files).
>
> Generally, if you have folder names, they should follow package naming conventions in Java, IMO.

Agreed - I hadn't thought of package issues earlier.

This change will happen later in the week.

> There are other class and package conflicts which should probably be addressed, such as naming classes default or having a leading number.  This directly comes from the JSON filename, and I have been able to rework around some of the issues.  I am unsure how many are left.
>
> John

Very good.  In general we've tried to be very observant of the following naming conventions.  I think they are compatible with JSON best practices, do your agree?  Further improvement is always welcome.  Am happy to examine and fix any apparent missteps.

==========================================================================================================
X3D Scene Authoring Hints: Naming Conventions
http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions

     Using clear and consistent names for node names and DEF labels greatly improves the clarity of how a scene work. In effect, names can make the purpose of a scene self-documenting.
     CamelCaseNaming: capitalize each word, never use abbreviations, strive for clarity, and be brief but complete.
     startWithLowerCaseLetter when defining field names (i.e. attributes) within Prototypes and Scripts.
     Ensure consistent capitalization throughout. Of note: the Windows operating system is not case sensitive, but http servers are. Thus mismatched capitalization can hide target files, and this error only is revealed when placed on a server.
     Use the underscore character ("_") to indicate subscripts on mathematical variables. Otherwise avoid use of underscores since they look like whitespace when part of a URL address.
     Avoid use of hyphens ("-") since these are erroneously turned into subtraction operators when converted into class or variable names.
     Avoid use of space characters, 'apostrophes' and "quotation marks" in file names since they can cause lots of problems for tools and search, especially when going from one operating system to another.
     Naming conventions can apply to .x3d files and reference files, as well as Prototype names, field names, and DEF/USE names. Starting names similarly (e.g. NavigationWalk, NavigationFly) can help alphabetize with indexing in the pretty-print HTML documentation, thus improving readability and searchability.
     There are multiple requirements for characters allowed in DEF/USE names.
         .x3d, .x3db encodings: must follow XML requirements for ID/IDREF data type.
         .x3dv, .wrl encodings: must follow ClassicVRML Grammar requirements for Id/IdFirstChar.
     Most restrictive and most interoperable guidance regarding choice of characters in names: can start with letter or underscore character, but not a number or a colon. Can then include letters, numbers, hyphen, underscore, or period characters. This interoperability is important so that files can be converted equivalently between encodings without validation problems.
     Use lower case for filename extensions. Examples: .png .jpg .txt. Although Windows systems are insensitive to upper/lower case, any differences will cause "file not found" failures on Unix systems (Apple, Linux) and http servers.
     Be consistent. When multiple files pertain to a single entity, start with the same name so that they will alphabetize adjacent to each other in the catalog and the directory listings. Examples: WaypointInterpolatorPrototype.x3d WaypointInterpolatorExample.x3d WaypointInterpolatorExample.png
     Similarly good choices for directory and subdirectory names can help keep scene names terse.
     Of related interest for DEF/USE and name attributes, focusing on Unicode characters: W3C Recommendation Extensible Markup Language (XML) 1.0, Appendix J: Suggestions for XML Names.

Naming of multiple similar autogenerated files: Concatenate the following name components as appropriate. Separate components by period characters, since underscores disappear as part of a url and since hyphens will break across a line.

     ConsistentDescriptiveName
     .PhysicalLocation (for example .KauaiHawaii)
     .SequenceNumber
     .01Month200x
     .ext

General notes on naming conventions:

     These conventions are suitable for X3D scenes, XML tagset design, and corresponding Java classes.
     This approach matches the node and field naming conventions in the X3D Specification (and most XML).
     (Ironic) Success Metric: when is a name successful?
     Answer: when no one has to discuss that name any more.
==========================================================================================================

p.s. do you have a better suggestion for delimiters than periods for the extra-long-set-of-autogenerated filenames case above?


> *From: *Don Brutzman <mailto:brutzman at nps.edu>
> *Sent: *Sunday, January 1, 2017 6:32 PM
> *To: *yottzumm at gmail.com <mailto:yottzumm at gmail.com>
> *Cc: *x3d-public at web3d.org <mailto:x3d-public at web3d.org>; Roy Walmsley <mailto:roy.walmsley at ntlworld.com>
> *Subject: *Re: X3D Java SAI...compileable examples and uncompileable examples
>
>
>
> thanks John, have downloaded and will check. much appreciated!
>
>
>
> so does your revised email mean that we don't need to rename archive?  was prepared to eliminate stumbling blocks and change
>
>
>
>                 Vrml2.0Sourcebook
>
> to
>
>                 Vrml2Sourcebook
>
>
>
> if that seems advisable.
>
>
>
>
>
> On 12/31/2016 4:06 PM, yottzumm at gmail.com wrote:> Compileable examples:  http://coderextreme.net/GoodJava.tar.gz 2487
>
>>
>
>> Uncompileable examples: http://coderextreme.net/BadJava.tar.gz  1431
>
>>
>
>> JavaSerializer.js in X3DJSONLD still needs work.  Not sure about Java SAI yet.
>
>>
>
>> Grab them while they are still available!
>
>>
>
>> John
>
>
>
> all the best, Don
>
> --
>
> Don Brutzman  Naval Postgraduate School, Code USW/Br       brutzman at nps.edu
>
> Watkins 270,  MOVES Institute, Monterey CA 93943-5000 USA   +1.831.656.2149
>
> X3D graphics, virtual worlds, navy robotics http://faculty.nps.edu/brutzman
>
>
>


all the best, Don
-- 
Don Brutzman  Naval Postgraduate School, Code USW/Br       brutzman at nps.edu
Watkins 270,  MOVES Institute, Monterey CA 93943-5000 USA   +1.831.656.2149
X3D graphics, virtual worlds, navy robotics http://faculty.nps.edu/brutzman