+1
Principle of least surprise applies to every API you create.
> On Mar 19, 2015, at 6:38 PM, Chris Westin <chriswesti...@gmail.com> wrote:
>
> In the course of things I've been doing, I've been cleaning up a large
> number of compilation warnings. These can help us find problems, so it pays
> to eliminate them whenever possible.
>
> One set concern dealing with resource leaks from failing to close() an
> AutoCloseable or Closeable. When I see these, I can't always tell if the
> resource is being leaked or not, because I can't always tell if we're
> creating a new resource, or retrieving a pre-existing managed one.
>
> For example, DrillbitContext.getClusterCoordinator() returns a
> ClusterCoordinator that can be used to execute cross-cluster
> synchronization; the DrillbitContext manages this, so I don't have to worry
> about closing it when I'm done using it.
>
> On the other hand, BufferAllocator.getChildAllocator() creates a new
> allocator that I do have to worry about closing when I'm done with it. I
> happen to know that because I'm doing some work on the allocators. But if I
> wasn't familiar with the code, and the calling file is full of warnings, I
> might not notice and take care of that.
>
> In this latter case, I could have been tipped off if the method name was
> instead "createChildAllocator." That's a strong hint that a new resource is
> being created. ("newChildAllocator" would have also tipped me off, but I
> happen to prefer "create.")
>
> So, if you're creating new resources, please make that clear from the
> method name.
>
> Chris
