UContracts a DSL to document and validate structural requirements of frameworks

Can we prevent re-use bugs?

A. Lozano, K. Mens, and A. Kellens, “Usage contracts: offering immediate feed- back on violations of structural source-code regularities”. (SciCo’15).

uContracts Motivation (1/2)

• Evolving an application requires keeping the:

• Design knowledge

• Architectural integrity

• They facilitate the introduction of substantial changes without introducing bugs

• BUT Design knowledge

• is not documented

• initial developers move on

• BUT Substantial changes may degrade the architectural integrity


• Evolving an application requires keeping the:

• Design knowledge

• Architectural integrity

• They facilitate the introduction of substantial changes without introducing bugs

• BUT Design knowledge

• is not documented

• initial developers move on

• BUT Substantial changes may degrade the architectural integrity

what is worthy of being documented?documenting is a loss of time!

documenting disrupts my work flow!who will keep that up-to-date?


• Programmers use recurrent uniformities of related code (idioms, naming conventions, design patterns....) to:

• preserve architectural constraints

• keep in a single artifact (source-code) all the information they need

!• Complying with them facilitate future changes:

• because they convey assumptions (correctness)

!• It would be useful to document them (within the code) and validate

them (automatically).

uContracts Idea behind: unitTesting for usage expectations

Provider

Consumer

uses

UsageContract

describesexpectations

of

shouldcomplywith


copyFrom: anEntity within: aVisitor

copyFrom: anEntity within: aVisitor super copyFrom: anEntity within: aVisitor ...

inheritsfrom

All overriders of copyFrom:within: should start with a super call


of

shouldcomply

with


classesInFAMIXSourcedEntityHierarchycopyFromWithinWithCorrectSuperCall

FAMIXSourcedEntityContract

EContract

classesInFAMIXSourcedEntityHierarchy <liableHierarchy:#FAMIXSourcedEntity>

copyFromWithinWithCorrectSuperCall <selector:#copyFrom:within:>contract require: condition beginsWith: (condition doesSuperSend: #copyFrom:within:) if: (condition isOverridden)

Liable entity

Contract term

Contract conditions

copyFrom: anEntity within: aVisitor

copyFrom: anEntity within: aVisitor super copyFrom: anEntity within: aVisitor ...

inheritsfrom

All overriders of copyFrom:within: should start with a super call


of

shouldcomply

with




EContract



Liable entity

Contract term

Contract conditions

Liable classes•liableClass: aRegExp / exceptClass: aRegExp •liableHierarchy: aClassName / exceptHierarchy: aClassName •liablePackage: aRegExp / exceptPackage: aRegExp




EContract



Liable entity

Contract term

Contract conditions

Liable classes•liableClass•liableHierarchy•liablePackage

Liable methods•selector: aRegExp / exceptSelector: aRegExp •protocol: aRegExp / exceptProtocol: aRegExp •/ exceptClass: aClassName selector: aSelector




EContract



Liable entity

Contract term

Contract conditions


Liable methods•selector•protocol•/ exceptClass

Contract terms•require: aCondition •suggest: aCondition •require: aCondition if:anotherCondition •suggest: aCondition if:anotherCondition




EContract



Liable entity

Contract term

Contract conditions



Contract terms•require•suggest•require•suggest

Contract conditions•assigns: aRegExp •calls: aRegExp •references: aRegExp •returns: anExpression •doesSuperSend: aRegExp •doesSelfSend: aRegExp •inProtocol: aRegExp •isOverridden: aSelector •isOverridden •isImplemented: aSel •custom: aVisitor




EContract



Liable entity

Contract term

Contract conditions



Contract terms•require•suggest•require•suggest

Contract conditions•assigns•calls•references•returns•doesSuperSend•doesSelfSend•inProtocol•isOverridden•isOverridden •isImplemented•custom

Contract conditions•and: aCond1 with: aCond2 •or: aCond1 with: aCond2 •not: aCond !•beginsWith: aCond •endsWith: aCond •does: aCond after: aCond2 •does: aCond before: aCond2

uContracts Validation with an Industrial Application

• Interactive web application for event & resource planning

• developed in Pharo Smalltalk

• uses the Seaside web development framework.

• Medium size

• Packages: 45

• Classes: 827

• Methods: 11777

• LOCs: 94151

Certain methods should not be called directly

• Certain methods should not be called directly from within interface code


liable classes

contract

Marking dirty objects

• State changes must mark model objects as dirty


liable classes

contract

Initialization via database

• Requires super call


liable classes

contract

Call ordering within cascade

• Certain messages need to be sent at the end of a method


liable classes




liable classescontract




liable classescontract

contractWithInCascadeVisitor extends CustomConditionVisitor

uContracts Screenshots


• 13 contracts defined in less than 2 days

• 5 for model entities -> 3c found errors (88)

• 214 liable classes

• 2 for persistent entities -> 2c found errors (2)


• 6 for interface code -> 4c found errors (11)



ContractLiable

MethodsExcept. Errors-Dic Errors-Mar

Certain methods should not be called directly

7410 0 3 2

Marking dirty objects 333 5 7 2

Initialization via database 44 0 1 0

Call ordering within cascade 531 0 0 0

uContracts Reduce inhibitors to document design rationale!

Lozano, A., Kellens, A., and Mens, K. “Usage contracts: offering immediate feed- back on violations of structural source-code regularities”. (SciCo’15).


What is valuable documentation?

Why should I do it?

What about true-but-harmless violations?

That disrupts my work flow!

What else should I keep up-to-date?



What is valuable documentation? document when you find violations

Why should I do it?







Why should I do it? violation are reported 'on the fly'

within the IDE and by priority









document the importance of a condition

'turn-off' harmless violations












contract definition is done during development

uContracts is SmallTalk: an internal DSL seamlessly integrated with Pharo.











contract definition is done during development

uContracts is SmallTalk: an internal DSL seamlessly integrated with Pharo.


nothing!What else should I keep up-to-date?


Conclusions

• It is possible to:

• reduce inhibitors to document design rationale

• prevent reuse bugs

• 2 days for 101 errors fixed

• these errors will not occur again (validated on the fly)

Questions?

Angela Lozano

[email protected]

F.10.733

mailto:[email protected]

Software

UContracts a DSL to document and validate structural requirements of frameworks