uContracts is a technique that uses contracts defined in code to validate source code against common patterns and conventions, providing immediate feedback on violations. This helps document design rationale and prevent reuse bugs. The paper presents uContracts and demonstrates how it was used to define contracts in an industrial application in just two days, finding and fixing 101 errors. uContracts reduces inhibitors to documentation by integrating contract definition and validation directly into the development workflow and IDE.

1. 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).

2. 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

3. 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
what is worthy of being documented?
documenting is a loss of time!
documenting disrupts my work flow!
who will keep that up-to-date?

4. uContracts
Motivation (2/2)
• 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).

5. uContracts
Idea behind: unitTesting for usage expectations
Provider
Consumer
uses
Usage
Contract
describes
expectations
of
should
comply
with

6. uContracts
Idea behind: unitTesting for usage expectations
copyFrom: anEntity within: aVisitor
copyFrom: anEntity within: aVisitor
super copyFrom: anEntity within: aVisitor
...
inherits
from
All overriders of
copyFrom:within:
should start with a
super call
describes
expectations
of
should
comply
with

7. uContracts
Idea behind: unitTesting for usage expectations
classesInFAMIXSourcedEntityHierarchy
copyFromWithinWithCorrectSuperCall
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
...
inherits
from
All overriders of
copyFrom:within:
should start with a
super call
describes
expectations
of
should
comply
with

8. uContracts
Idea behind: unitTesting for usage expectations
classesInFAMIXSourcedEntityHierarchy
copyFromWithinWithCorrectSuperCall
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
Liable classes
•liableClass: aRegExp / exceptClass: aRegExp
•liableHierarchy: aClassName / exceptHierarchy: aClassName
•liablePackage: aRegExp / exceptPackage: aRegExp

9. uContracts
Idea behind: unitTesting for usage expectations
classesInFAMIXSourcedEntityHierarchy
copyFromWithinWithCorrectSuperCall
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
Liable classes
•liableClass
•liableHierarchy
•liablePackage
Liable methods
•selector: aRegExp / exceptSelector: aRegExp
•protocol: aRegExp / exceptProtocol: aRegExp
•/ exceptClass: aClassName selector: aSelector

10. uContracts
Idea behind: unitTesting for usage expectations
classesInFAMIXSourcedEntityHierarchy
copyFromWithinWithCorrectSuperCall
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
Liable classes
•liableClass
•liableHierarchy
•liablePackage
Liable methods
•selector
•protocol
•/ exceptClass
Contract terms
•require: aCondition
•suggest: aCondition
•require: aCondition if:anotherCondition
•suggest: aCondition if:anotherCondition

11. uContracts
Idea behind: unitTesting for usage expectations
classesInFAMIXSourcedEntityHierarchy
copyFromWithinWithCorrectSuperCall
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
Liable classes
•liableClass
•liableHierarchy
•liablePackage
Liable methods
•selector
•protocol
•/ exceptClass
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

12. uContracts
Idea behind: unitTesting for usage expectations
classesInFAMIXSourcedEntityHierarchy
copyFromWithinWithCorrectSuperCall
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
Liable classes
•liableClass
•liableHierarchy
•liablePackage
Liable methods
•selector
•protocol
•/ exceptClass
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

13. 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

14. Certain methods should not be called directly
• Certain methods should not be called directly
from within interface code
uContracts
Validation with an Industrial Application
liable classes
contract

15. Marking dirty objects
• State changes must mark model objects as
dirty
uContracts
Validation with an Industrial Application
liable classes
contract

16. Initialization via database
• Requires super call
uContracts
Validation with an Industrial Application
liable classes
contract

17. Call ordering within cascade
• Certain messages need to be sent at the end
of a method
uContracts
Validation with an Industrial Application
liable classes

18. Call ordering within cascade
• Certain messages need to be sent at the end
of a method
uContracts
Validation with an Industrial Application
liable classes
contract

19. Call ordering within cascade
• Certain messages need to be sent at the end
of a method
uContracts
Validation with an Industrial Application
liable classes
contract
contract
WithInCascadeVisitor extends CustomConditionVisitor

20. uContracts
Screenshots

21. uContracts
Validation with an Industrial Application
• 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)
• 75 liable classes
• 6 for interface code -> 4c found errors (11)
• 598 liable classes

22. uContracts
Validation with an Industrial Application
Contract
Liable
Methods
Except. 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

23. 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).

24. uContracts
Reduce inhibitors to document design rationale!
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?
Lozano, A., Kellens, A., and Mens, K. “Usage contracts: offering immediate feed- back on violations of structural source-code
regularities”. (SciCo’15).

25. uContracts
Reduce inhibitors to document design rationale!
What is valuable documentation? document when you find violations
Why should I do it?
What about true-but-harmless
violations?
That disrupts my work flow!
What else should I keep up-to-date?
Lozano, A., Kellens, A., and Mens, K. “Usage contracts: offering immediate feed- back on violations of structural source-code
regularities”. (SciCo’15).

26. uContracts
Reduce inhibitors to document design rationale!
What is valuable documentation? document when you find violations
Why should I do it? violation are reported 'on the fly'
within the IDE and by priority
What about true-but-harmless
violations?
That disrupts my work flow!
What else should I keep up-to-date?
Lozano, A., Kellens, A., and Mens, K. “Usage contracts: offering immediate feed- back on violations of structural source-code
regularities”. (SciCo’15).

27. uContracts
Reduce inhibitors to document design rationale!
What is valuable documentation? document when you find violations
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
What about true-but-harmless
violations?
That disrupts my work flow!
What else should I keep up-to-date?
Lozano, A., Kellens, A., and Mens, K. “Usage contracts: offering immediate feed- back on violations of structural source-code
regularities”. (SciCo’15).

28. uContracts
Reduce inhibitors to document design rationale!
What is valuable documentation? document when you find violations
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
What about true-but-harmless
violations?
contract definition is done during development
uContracts is SmallTalk: an internal DSL
seamlessly integrated with Pharo.
That disrupts my work flow!
What else should I keep up-to-date?
Lozano, A., Kellens, A., and Mens, K. “Usage contracts: offering immediate feed- back on violations of structural source-code
regularities”. (SciCo’15).

29. uContracts
Reduce inhibitors to document design rationale!
What is valuable documentation? document when you find violations
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
What about true-but-harmless
violations?
contract definition is done during development
uContracts is SmallTalk: an internal DSL
seamlessly integrated with Pharo.
That disrupts my work flow!
nothing!What else should I keep up-to-date?
Lozano, A., Kellens, A., and Mens, K. “Usage contracts: offering immediate feed- back on violations of structural source-code
regularities”. (SciCo’15).

30. 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)

31. Questions?
Angela Lozano
alozano@soft.vub.ac.be
F.10.733