directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ole Ersoy <ole.er...@gmail.com>
Subject Re: Method Naming Conventions
Date Thu, 08 Mar 2007 02:01:15 GMT
Stefan,

Brilliant!!  Yeehah!!  Can't wait to test it out.  I'll start adding 
notes around it to the contributor docs asap.

Thanks,
- Ole

Stefan Seelmann wrote:
> 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 schrieb:
>   
>> 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