[WebODF] coding rules for types

[Jos van den Oever]

Hi all,

In our codebase we use some annotations differently. This can be 
confusing for new developers that are not too familiar with Closure 
Compiler annotations.

So I'm proposing some rules that we'll try to enforce by linting.

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

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.

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.

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

What do you think of this proposal?

Cheers,
Jos