directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefan Seelmann <seelm...@apache.org>
Subject Re: Method Naming Conventions
Date Wed, 07 Mar 2007 15:42:45 GMT
Ole, you may take a look to http://jautodoc.sourceforge.net/ . It is an 
Eclispe plugin, just press Strg+Alt+J and it generates Javadoc.


ole ersoy 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
>
>
>


Mime
View raw message