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
