directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Trustin Lee" <trus...@gmail.com>
Subject Re: Method Naming Conventions
Date Mon, 12 Mar 2007 02:36:31 GMT
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 <ole.ersoy@gmail.com> 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

Mime
View raw message