[
https://issues.apache.org/jira/browse/COLLECTIONS-704?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16702258#comment-16702258
]
Gary Gregory commented on COLLECTIONS-704:
------------------------------------------
The best thing to do here IMO is to rename the params and update the Javadoc.
IOW make the comments and names reflect the code. A PR would be welcome :)
https://github.com/apache/commons-collections
> GrowthList: ambiguity in constructor argument
> ---------------------------------------------
>
> Key: COLLECTIONS-704
> URL: https://issues.apache.org/jira/browse/COLLECTIONS-704
> Project: Commons Collections
> Issue Type: Improvement
> Components: List
> Affects Versions: 4.0, 4.2
> Reporter: K P
> Priority: Minor
>
> The javadoc of constructor
> {{[GrowthList|https://commons.apache.org/proper/commons-collections/apidocs/org/apache/commons/collections4/list/GrowthList.html#GrowthList-int-](int
> initialSize)}}
> states:
> {{initialSize}} - the initial size of the ArrayList
>
> However, this is confusing terminology: As the initialSize argument is passed
> directly to the internal ArrayList constructor, this is effectively the
> initial +capacity+. The +capacity+ is NOT the same as the actual list +size+.
> So after this constructor is called, the actual list.size() is still 0. This
> is identical to the normal ArrayList constructor's behavior of course.
> However, the GrowthList javadoc is confusing by explicitly claiming this is
> the "_initial size_", which may lead the reader to think that this
> constructor effectively grows the initial list to an actual given size - size
> in the sense the word is used everywhere else in the javadoc of this class.
> As opposed to the javadoc of Java's ArrayList, where they clear use the
> terminology "_the initial capacity of the list_", to avoid any confusion
> between the notion of internal array capacity and the list size.
> If, long ago, this GrowthList constructor was once intended to really set the
> ini**tial size, then is clearly not what the code does.
> However, if this never was the intention, and this was just intended to be an
> initial capacity, as the normal ArrayList, then the javadoc of GrowthList
> should be slightly reworded, to avoid ambiguity or misunderstanding, and make
> clear this is just the initial _capacity_ of the underlying ArrayList; not
> the initial _size_ of the list.
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
