[API] Some more cleanup ideas

[Stephan Bergmann]

On 12/03/2012 10:53 AM, Michael Meeks wrote:
> On Fri, 2012-11-30 at 18:53 +0100, Lubos Lunak wrote:
>> On Friday 30 of November 2012, Stephan Bergmann wrote:
>>> I'm not sure this is a good move.
> ...
>>> Which leaves us with the benefit of shorter, less visually cluttered
>>> declarations of C++ functions.  But, as I argue above, I am not sure
>>> that is an overall benefit at all.
>
> 	I'm convinced it is a benefit :-) - and it's interesting; there have
> been a string of decisions in the past where we have decided to go for
> more readable code over (IMHO) gross verbosity:
>
> -	rtl::OUString( RTL_USTRING_VERYLONGNAME( "foo" ) )
> +	"foo"
>
> 	to me is a -massive- improvement in readability. More minor ones are:
>
> -	rtl::OUString
> +	OUString
>
> 	Many of these have been resisted with the same "no benefit" argument. I
> believe that every redundant token we can clarify, and simplify makes
> reading and getting into the code much easier for new people. Hackers
> have to spend tons of their time reading and un-tangling code, so
> maximum readability is key.

I agree that the string literal clean-up is a big win, makes it much 
more pleasant to read and write code, and that I was wrong in 
considering it syntactic sugar that would likely not be worth the effort.

However, in this case, I argue that leaving the dynamic exception 
specifications in does have a benefit, in a part of the original mail 
that got elided.

> 	In my view the inevitable line-wrapping / 80 char bustage that huge
> long exception descriptions bring brings a significant impairment of
> readability. What should read as a simple interface implementation (and
> to be fair looks reasonably clean and readable as IDL) gets turned into
> something much fouler in the header & impl. The css:: mangling helps in
> some minor way with this - but I feel it is far better to hide as much
> as humanly possible of that duplicate guff.

IMO, the duplication is beneficial here.  Just as we duplicate, say, a 
method's return type and parameter types from the UNOIDL specification 
into the C++ implementation -- and not only because we are technically 
forced to, but also because it makes the resulting C++ code so much more 
comprehensible.

Abbreviating "com::sun::star::" to "css::" and folding explicitly listed 
subclasses of RuntimeException can likely go a long way to reduce 
accidental complexity while keeping the necessary complexity evident.

>
>>   So, in practice, the specifications in our case are like writting out asserts
>> in the code, and the only questions that there should be are whether it makes
>> sense to have such asserts and whether they are worth the code clutter.
>
> 	Quite. Personally - I'm deeply unconvinced that we can afford to have a
> code-base where all manner of unexpected side-effects remain un-checked
> at compile-time etc. The "only call methods that throw exceptions
> mentioned above" criteria is (to me) far too opaque to have any
> reasonable chance of reviews and newbie implementers from following it -
> worse manual checking of that sort of tedious detail, even if it is done
> is highly error prone: and I suspect is done only one way. Who - when
> changing a function checks all call-sites of it to see if they declare
> that exception ? ;-)

Where does the "only call methods that throw exceptions mentioned above" 
criterion come form?  It misses a fundamental part of programming with 
exceptions, namely the necessity to match exceptions thrown by a 
function's implementation to the function's interface.

Stephan