Uploaded image for project: 'Technical Advisory Board'
  1. Technical Advisory Board
  2. TAB-1524

Naming Conventions - underscore vs. dashes

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: New
    • Priority: Major
    • Resolution: Unresolved
    • Affects Version/s: TAXII Version 2.0 CSPRD01
    • Fix Version/s: None
    • Component/s: None
    • Labels:
      None
    • Environment:

      Style

    • Proposal:
      Hide

      I heavily recommend discovering the distinctions meant to be represented by naming and color/style changes and asking if that is the best way to convey that information to the reader. Esp. questioning the use of color.

      Show
      I heavily recommend discovering the distinctions meant to be represented by naming and color/style changes and asking if that is the best way to convey that information to the reader. Esp. questioning the use of color.

      Description

      1.3.1 Naming conventions reads:

      *****
      All type names, property names and literals are in lowercase. Words in property names are separated with an underscore (_), while words in type names and string enumerations are separated with a dash . All type names, property names, object names, and vocabulary terms are between three and 250 characters long.
      *****

      Are all property names or words in type names and string enumerations more than one word?

      I ask because you list property names like "title" (3.6.1) and "description" (also 3.6.1), which don't use the underscore at all. Assuming "string" is a type name, that is an example of a type name that doesn't use the hash.

      More troubling though is your use of color in 1.3.2, which is likely to render your work inaccessible and/or difficult to use. See: http://blog.usabilla.com/how-to-design-for-color-blindness/

      Perhaps the best question to ask in the TC is what goal do you have for the distinctions you make with naming and color/font/font style?

      That is to ask, for example, how does having "resource and type names in red with a light red background" especially since Type appears as a column header in a table and below it appears "string." Does using the red background assist the reader in realizing that is a type declaration?

      Or is there an important relationship between type and resource that is being signaled by sharing the same color?

      Whether recorded in your next draft or not, I think calling out each distinction and capturing by the TC of what distinction it makes apparent to the reader (other than yes, it is red, blue, gray, etc.) would be an extremely useful exercise.

      It may be that some important distinction lurks under those colors/styles that the TC automatically sees but the average reader will not.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              patrick Patrick Durusau
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated: