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
Am Montag, 10. Februar 2014, 13:32:39 schrieb 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.
It's confusing for some old developers (like me) as well :)
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).
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.
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
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
4) Each non-constructor function must have a @return declaration.
+1 Thanks for pushing for these coding rules, really time Friedrich -- Friedrich W. H. Kossebau // KO GmbH http://kogmbh.com/legal/
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
Ok, so starting now these rules apply: 1) For the types 'string', 'number', 'boolean' and 'function', the '!' shall be written explicitly. 2) For the types 'Object', 'Array' and 'Function', the '?' shall be written explicitly. 3) Objects will always explicitly have 'string' as the key. So each Object in a type definition starts with 'Object.<string,'. 4) Each non-constructor function must have a @return declaration. Please follow them when writing new code and doing review requests. If anyone feels like writing linting code for this, that would be great. Cheers, Jos On 02/11/14 10:58, Philip Peitsch wrote:
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
participants (3)
-
Friedrich W. H. Kossebau
-
Jos van den Oever
-
Philip Peitsch