Re: [sca-c-cpp] NEW ISSUE: Document conventions

[Andrew Borley <BORLEY@uk.ibm.com>]

This issue has been assigned id CCPP-52
in the Jira system

See http://www.osoa.org/jira/browse/CCPP-52

Andrew

____________________________________________________________

Andrew Borley
Websphere ESB Development
Tel: 245393 Ext: +44 (0) 1962 815393 Mob: +44 (0) 7971 805547
E-mail: borley@uk.ibm.com
Mailpoint 211, IBM (UK) Ltd, Hursley Park, Winchester, Hants, SO21 2JN
____________________________________________________________

From:	Bryan Aupperle <aupperle@us.ibm.com>
To:	sca-c-cpp@lists.oasis-open.org
Date:	01/12/2008 18:59
Subject:	[sca-c-cpp] NEW ISSUE: Document conventions

---

Target:                SCA C++
and C C&I Specifications:  sca-cppcni-1.1-spec-cd01-rev3.doc and
sca-ccni-1.1-spec-cd01-rev3.doc

Description: 

The SCA Liaison committee has asked us to add a small section on naming
conventions to the 
frontmatter of the SCA C++ and C C&I specifications. 

This needs to cover conventions for the names that are defined by SCA in
particular: 

- names of elements and attributes in XSD files 
- names of intents 

This would be a good place to document typographic conventions as well:

- XML attributes are identified in text as @attribute
- Language identifiers used in text are in courier
- Literals in text are in italics 

Proposal: 

To each document, add a new section - 1.4: 

1.4 Conventions 

1.4.1 Naming Conventions 
This specification follows some naming conventions for artifacts defined
by the specification, 
as follows:

• For the names of elements and the names of attributes within XSD files, the names follow
  the CamelCase convention, with all names starting with a lower case letter.
  e.g. <element name="componentType" type="sca:ComponentType"/>
• For the names of types within XSD files, the names follow the CamelCase convention with
  all names starting with an upper case letter
  e.g. <complexType name="ComponentService">
• For the names of intents, the names follow the CamelCase convention, with all names
  starting with a lower case letter, EXCEPT for cases where the intent represents an
  established acronym, in which case the entire name is in upper case.
  An example of an intent which is an acronym is the "SOAP" intent.

1.4.2
Typographic Conventions 
This specification follows some typographic conventions for some specific
constructs

• XML attributes are identified in text as @attribute
• Language identifiers used in text are in courier
• Literals in text are in italics

Bryan Aupperle, Ph.D.
STSM, WebSphere Enterprise Platform Software Solution Architect
Master Inventor

Research Triangle Park,  NC 
+1 919-254-7508 (T/L 444-7508)
Internet Address: aupperle@us.ibm.com

---

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU