[WebODF] coding rules for types

[Philip Peitsch]

>> 1) For the types 'string', 'number', 'boolean' and 'function', the '!'
>> shall not be written explicitly.
>>
>> Rationale: Prepending a '!' to a type means that it is not null. For esp
>> string, number and boolean, it's weird to have the null value. These
>> types occur a lot and making the '!' explicit would mean a lot of '!' in
>> the code.
>> In an Object with string keys, the '!' looks especially silly:
>>    Object.<!string,!Object>
>> (Using undefined or null as a key will change it to 'undefined' and
>> 'null' respectively).
>
> Meh, I would rather prefer the opposite, have all kind of types be handled in
> the same way. So always writing explicitely the if-nullable state.
>
> Rationale: Making a distinction between the different kind of types only
> complicates things. Just see how it took us more up to a year to get it
> finally. Also would be consistent with the rules 2) to 4) where we also write
> explicitely the defaults.

Based on the errors we're finding in CC's own externs, I am leaning
towards explicit is best. In addition, it isn't that many extra chars
to type for the clarity provided :).

So +1 for always using explicit !/?

>
>> 2) For the types 'Object', 'Array' and 'Function', the '?' shall be
>> written explicitly.
>>
>> Null pointers can be a problem. The compiler checks the nullness when
>> passing an object but not when accessing a member. Keeping awareness of
>> nullness high is good.
>
> +1

+1

>
>> 3) Objects will always explicitly have 'string' as the key. So each
>> Object in a type definition starts with 'Object.<string,'.
>>
>> Rationale: Any other type makes no sense, because in JS the key type is
>> always a string anyway.
>
> +1

+1

>
>> 4) Each non-constructor function must have a @return declaration.
>
> +1

+1

-- 
Philip Peitsch
Mob: 0439 810 260