Question

Who has the most readable and useful function/class commenting convention?
I’m not looking for something that generates docs, but I’m considering adopting something like JavaDoc because all the info is there.

/**
 * This function processes data
 * 
 * @param p1 the first piece of data
 * @param p2 the second piece of data
 * @return   true if the processing was successful, else false
 */
function ProcessData(p1, p2){

or some other hand crafted thing?

/////////////////////////////////
// This function processes data
//
// p1    the first piece of data
// p2    the second piece of data
// returns true if processing was successful, else false
function ProcessData(p1, p2){

Any reasonable argument for single line comments over multiline?

I’d like to apply a convention to all languages I use, so please share any language-specific or language-agnostic conventions you have!

Answer 1

For the comment style, I would definitely go for multiline, as that’s what they are for – it just looks cleaner overall.

For the params, the first one is more powerful, as you can specify the type of each information: ‘@type name description’, vs ‘name description’ and it’s what I usually see in C type languages.