Method Naming Conventions

[ole ersoy]

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 ListFile create(ArrayListString paths)
   {
   IteratorString pathIterator = paths.iterator();
   ListFile fileList  = new ArrayListFile();
   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

Re: Method Naming Conventions

[Stefan Seelmann]

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 ListFile create(ArrayListString paths)
 {
 IteratorString pathIterator = paths.iterator();
 ListFile fileList  = new ArrayListFile();
 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
 
 
 

Re: Method Naming Conventions

[Stefan Seelmann]

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 ListFile create(ArrayListString paths)
{
IteratorString pathIterator = paths.iterator();
ListFile fileList  = new ArrayListFile();
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

Re: Method Naming Conventions

[Ole Ersoy]

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 ListFile create(ArrayListString paths)
{
IteratorString pathIterator = paths.iterator();
ListFile fileList  = new ArrayListFile();
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