FEB
7
2004
|
Argument Constraints in the Function DeclarationThe most annoying thing when writing public APIs is that it's a lot of redundant typing. A good API implementation should check all arguments and return a useful error message if an argument is invalid. Good API documentation should document which arguments values are valid and which return values are possible. Both tasks are work-intensive and annoying for the developer, which is probably one of the reasons why there so many bad APIs. /** * Sets the discount as percentage. * @param percentage the discount as percentage * @throws IllegalArgumentException if percentage < 0 or percentage > 100 */ void setDiscountPercentage(float percentage) { if ((percentage < 0.0) || (percentage > 100.0)) throw new InvalidArgumentException("percentage must be >=0 and <=100"); mPercentage = percentage; } /** * Gets the discount as percentage. * @return the discount as percentage. Guaranteed to be positive and not * higher than 100.0 */ float getDiscountPercentage() { assert (mPercentage >= 0.0) && (mPercentage <= 100.0); return mPercentage; }
So is it possible to remove this redundancy and specify the constraints only once? I think so. void setDiscountPercentage(float percentage(>=0.0,<=100.0)) { mPercentage = percentage; } float(>=0.0,<=100.0) getDiscountPercentage() { return mPercentage; } Each argument is followed by a list of comma-separated constraints that can be checked before executing the function. To make the syntax more crisp it is allowed to start the expressions directly with a comparison operator. They will then be executed with the function argument as first operand. It's also possible to use normal boolean expressions, for instance to check the length of a string: void setId(String id(!=null, id.length() > 0, id.length() <= 10)) { //... } The syntax looks pretty cryptic though, because the declaration becomes very long and the nesting of parentheses is confusing. An alternative would be to declare the assertions after the normal signature: void setDiscountPercentage(float percentage) with percentage: >=0.0, <=100.0 { mPercentage = percentage; } (float percentage) getDiscountPercentage() with percentage: >=0.0, <=100.0 { return mPercentage; } void setId(String id) with id: !=null, id.length() > 0, id.length() <= 10 { // ... } It's a little bit more verbose, and for return value constraints this syntax requires named return values, (int a, int b, int c) create3PositiveNumbers(int x) with a: >0 with b: >0 with c: >0 with x: >0 { return (x, x, x); } I think it's quite nice. A few random things:
|
![]() |
Comments
Something similar in standard c++
Interestimg article! In one of my projects I used a simple template class that did something similar in standard c++ for me.
I think it's a good solution as long as the C++ doesn't offer something better, because it also nicely documents the allowed range.
Christian
Disclaimer: This was from my memory so there might be coding errors in it.
OT: C++ and .NET
Since you also have an eye on .NET/CLI/C#, I think you might find the following link interesting. It's a presentation made by Herb Sutter. It was held at the last meeting of the C++ standard committee. It's basically talking about how C++ can become a "first class" CLI language.
http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1557.pdf
C++ and .NET
My favorite line is on page 4: "Attempt #1: _ugly_keywords. Users screamed and fled".
Someone should tell this to the Python guys...
I am not sure whether I like the binding though. It's putting a lot of (redundant) features in the language that blow it up quite a bit, and plain C++ is not exactly a small language. If you already know C++ and you want to take advantage of the existing CLR libaries and features it is certainly useful, especially to migrate existing code. But as a stand-alone language I would detest it :)
cool idea! As usual I got
cool idea!
As usual I got my own syntax. ;)
e.g.:
PS: How can I disable the wiki like features in this forum? Or how can I write a '[' so it is displayed as a squared bracket open.
Oh. And how to dissable this?
Oh. And how to dissable this?
e.g.:
Um... I think this only works when the syntax is as following:
like the gcc extensions for function attributes: http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html
Hmm... maybe we should ask the gcc guys to implement someting like an attribute:
check( expr )
Hmmm... or what do you think?
PS: I know, my english is horrible.
Encoding
void SomeClass::setValue( int newValue ) check( ( newValue % 8 ) == 0 )
IMHO The problem with that is the missing link between the argument and the constraint. The documentation tool would need to be pretty smart, and even then it may fail to find out your intention in some cases (if you use more than one argument in an assertion).
How can I disable the wiki like features in this forum? Or how can I write a ‘[’ so it is displayed as a squared bracket open.
The only way I know is to use HTML escaping with ASCII/Unicode code.
IMHO The problem with that is
IMHO The problem with that is the missing link between the argument and the constraint.
Um, yes, that's right. But I don't like the "with {PARAMETER_NAME}: <CONSTRAINT>" Syntax.
Maybe this is better:
e.g.:
IMHO The problem with that is
IMHO The problem with that is the missing link between the argument and the constraint.
Um, yes, that's right. But I don't like the "with {PARAMETER_NAME}: <CONSTRAINT>" Syntax.
Maybe this is better:
e.g.:
PS: Forgot some HTML escapeing.
Eiffel / Ada
You should have a look at the Eiffel language. They have Design by Contract, which consists of pre- and postconditions (and invariants) for your methods. E.g. translated to C++ this would look like:
The require clause must be obeyed by the caller of the method (or an exception is thrown) and the ensure clause promises that the method really does what it is suspected to do. So it is like a contract between caller (=client) and called (=server).
And it is of course also visible in the API documentation so people who use your classes have an exact view of your specifications.
People tried to add this to Java (iContract and such) but it is more a demonstration hack (embedded in comments etc.) which has nowhere the real power of the Eiffel language.
Another approach seems to come from Ada-like languages where you can specify types more exactly than in C-based languages.
Eiffel / Ada
You should have a look at the Eiffel language. They have Design by Contract
Yes, I know, this was basically a follow-up to this entry. I should have linked to it (it is still valid IMHO, but should be used for internal consistency checks only).
I think the problem with the Eiffel syntax is that it a) does not separate internal consistency checks (that may use private members and functions) from the public API contract and b) that there is no connection between the assertions/constraints and the arguments. A message "Your argument 'x' is wrong because it violated the constraint '>0'" is more useful than a long list of assertions, and it also helps for automatic documentation.
An advantage of the Eiffel syntax is that it allows to check not only arguments, but also the method's object. But this is also a disadvantage because it encourages bad design: you could use it to create objects with states that allow you to call methods only under certain circumstances. Sometimes you can't avoid it, but you should avoid it like the plague because it is so error-prone.
Pages