Hi Ole,
It might be a little bit off-topic, but I'd rather prefer 'get' to 'create'
because we can abstract the way it is returned by using the verb 'get'. It
can be cached somewhere and we could return a singleton later when we need
more optimization.
I also prefer not to add FromXXX to the method name because the parameter
itself should describe what the method creates a return value from. In the
example you gave, we already know that we creates a list of files from
'paths'. So we don't need to name it getFileListFromPathList. getFileList
will suffice.
Trustin
On 3/8/07, ole ersoy <[EMAIL PROTECTED]> wrote:
Hey Guys,
This is important for making server documentation wrt
code and general documentation and development as efficient as possible.
This is somewhat obvious to most of us, but is nice to have
wrt to new comers and for general communication and comprehension.
If we use method naming conventions we can have javadocs and other
documentation
completed automatically most of the time.
I'm working out some utility methods to submit to commons-io,
and did a little thinking about naming conventions in the context
of generating the javadocs, which I will also put in the ApacheDS
contributor
guide if we like it.
For instance I have this method:
public static List<File> create(ArrayList<String> paths)
{
Iterator<String> pathIterator = paths.iterator();
List<File> fileList = new ArrayList<File>();
while(pathIterator.hasNext())
{
fileList.add(new File(pathIterator.next()));
}
return fileList;
}
Initially I was thinking about naming it:
createFileListFromStringPathList.
But then I thought most of the information in the method name
is really in the structure of the method already.
We know that it creates a list of files based on looking at the return
type.
We know the input is a list of strings.
We see that it creates something based on the method name.
Pass these parameters through a formatting string and most of the javadoc
is done I think.
Thoughts?
(I mainly submitted this for awareness, I have to investigate javadoc
generation patterns in eclipse a little more)
(The thinking being that if we document our conventions and stick to them,
whenever a javadoc is missing, we could
look at the convention and know what the javadoc would be. It can then be
generated later, once the capability is ready)
Cheers,
- Ole
--
what we call human nature is actually human habit
--
http://gleamynode.net/
--
PGP Key ID: 0x0255ECA6
