问题
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!
回答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.
回答2:
Python uses RST.
You might be able to use Sphinx, it might do what you want.
回答3:
I suggest not commenting at all, but instead, giving meaningful self-explanatory names to p1 and p2.
As said here, "comments are not schindler's list. They are not pure good. They are, at best, a necessary evil"
来源：https://stackoverflow.com/questions/991820/function-class-comment-formatting-conventions