Hi Roger,
So do you think that this form for example:
(common prefix)
* @throws IndexOutOfBoundsException
* If {@code off} is negative, or {@code len} is negative,
* or {@code off + len} is negative or greater than the length
(array suffix)
* of the given array
(string suffix)
* of the given string
could be applied to both the array- and String-based write() variants?
Thanks,
Brian
On May 9, 2016, at 2:04 PM, Roger Riggs <roger.ri...@oracle.com> wrote:
>>> In the @throws IndexOutOfBounds I think it is easier to understand to say
>>>
>>> * or {@code off + len} is greater than {@code cbuf.length}
>>>
>>> It matches the code more closely.
>>
>> The reason for the verbiage is that it matches (module removal of a
>> redundant “or” in the throws verbiage) Reader.read(char[],int,int) with
>> which I thought it would good to be consistent in an operation-symmetric
>> sense:
>>
>> http://download.java.net/java/jdk9/docs/api/java/io/Reader.html#read-char:A-int-int-
>
> It better to propagate the best practices, not something that can be improved.
> Since you are updating the writing classes, I think it ok to put a lower
> priority on the Reader classes.
>
>>
>>> - Is not clear why the form of the added @throws is different between the
>>> methods (other than len = string.size()
>>
>> Writer.write(String,int,int) already had a throws exception for IOOBEs so I
>> was trying to be consistent with that:
>>
>> http://download.java.net/java/jdk9/docs/api/java/io/Writer.html#write-java.lang.String-int-int-
>
> I just think that {@code cbuf.length - off}, is not an intuitive way to talk
> about the out of range condition.
>
> The write(string, off, len) uses a better form and I think its more important
> that the methods in a
> class use the similar form. It is much more noticeable comparing two methods
> in a class
> than methods in different classes. (Fixing up Reader would be a different
> request).
>
>>
>>> line 214: add a spaces in "off+len"
>>>
>>> Most/All files have the same pattern. It would be nice to be consistent.
>>
>> Again, this is the same as in the extent Writer.write(String,int,int).
> This uses the form I think is more readable:
> 178 * or {@code off + len} is negative or greater than the
> length
