Re: [SpecGL Draft] E. Good Practice: Write sample code or tests.

Hi Karl
You go guy!.
More editorial comments.

At 02:28 PM 7/13/2004, you wrote:
>Good Practice:
>         Write sample code or tests.
>
>What does that mean?
>         For each feature, the WG might seek for early implementation 
> demonstrating the feature. If early

delete 'for'
s/demonstrating/to demonstrate/

>implementations are not available for different reasons (commercial 
>constraints, IPR), it will be beneficial to
>write test cases to figure out the use cases of the technology and to 
>create parts of a test suite.

Not sure what you are trying to say.  How about this:
If early implementations are not available (e.g., due to commercial 
constraints, IPR, etc.), it is beneficial to write test cases to illustrate 
a concept or use case of the technology. Additionally, these test cases can 
be incorporated into a test suite.

>
>Why should I care?
>         When a technology is created, it is very tempting to add many 
> features, because they really seem
>appealing or useful. Though defining a new feature doesn't mean that the 
>model is easily implementable or implementable at all.

Don't understand this.

>By creating early partial implementation (code) and/or writing test cases, 
>the WG is addressing part of the issues that a developer could meet during 
>the implementation phase.
>         WG will save time and resources because:
>                 - It will give examples to illustrate the specification
>                 - It will help to deal with issues resolution
>                 - it will help to have a pre-implementation report at CR 
> phase.
>                 - It will help to create a complete Test Suite.         - 
> It will encourage external implementations and therefore a more complete 
> implementation report.

Not sure how to rewrite this, but it does need improvement. Here is a try:
Why care?
Developing a partial implementation (sample code) or test cases can provide 
an understanding of a concept or feature as well as help to keep it 
focused.  It can save the WG and eventually implementers time and resources by:
++providing examples to illustrate the specification
++facilitating issue resolution
++helping to have a pre-implementation report at CR phase
++contributing to the development of a complete Test Suite
++encouraging external implementations and therefore a more complete 
implementation report.

>Related:
>         CSS Test Guidelines
>         RDF/OWL Method
>
>Techniques:
>         1. Try to associate developers to the Working Group progress 
> (Open source or commercial)
Awkward.  I don't know how to rewrite this.

>         2. For each submitted feature, request from the WG Member, one or 
> more test case demonstrating the use of this feature.

Suggest:  2. For each feature, request that WG members provide at least one 
test case demonstrating the use of the feature.

>         3. Do not input the feature inside a specification before to have 
> the associated test cases.
rewrite: 3. Do not put a feature into a specification without the 
corresponding test cases.

>         4. Create a template to write feature for the specification which 
> includes a test case section
suggest:  4. Create an authoring template for how to define/describe a 
feature which include a test case section.

>Examples:
>
>         RDF/OWL Jeremy Caroll?
>         XMLP ? Yves Lafon?
>         CSS editors are encouraged (required?) to provide tests with all 
> new content.

--lynne

Received on Wednesday, 14 July 2004 14:38:27 UTC