Most of the time, when I comment a method, I’ll follow this structure.
/**
* Short description of what the method does
*
* @param {Type} name. Description of the variable.
*
* @return {Type}. What the return is.
*/
Now if I have a method called uploadData, which takes one parameter, data, is it still necessary to give this parameter a description?
I realize necessary is kind of subjective in this case, but I’m curious as to what the general consensus is. For the time being I’ve been giving them all descriptions just to keep the consistency of the comments, but it does seem like it’s a very unneeded.
If it makes any difference, the languages I use are Javascript, Java and PHP.
comments
0
The fact that the only parameter to an upload function is to do with the upload data is not noteworthy. What is worth mentioning is e.g. what format this is in (is it a String giving the name of a local file? a string constituting the data itself? a byte stream?), what restrictions it is subject to (unlimited? no more than 10MB? only 10 per day?), whether all of the values technically allowed by the type are okay (is NULL okay? is the empty array okay? does it have to be a valid UTF8 byte sequence?), etc.
If all of these issues are obviously clear to any caller of the method (e.g. if the parameter is a specifically constructed upload object which ensures that only valid data can go in), then go ahead and leave the parameter undocumented. But often it turns out there are additional preconditions, and it is almost always a good idea to make these explicit.
2
I only describe parameters when I’m actually providing the reader with information. The definition of information is “adding to someone’s knowledge”. If the description is not adding to someone’s knowledge, then it is not information and I leave it out.
/**
* @param string username. The username. <--not providing information
*/
Also Martin Fowler says if you need to add a comment, you probably need to use a better name for the parameter. That should apply to Javadoc too.
Is there a need to comment obvious parameters? [duplicate]
Most of the time, when I comment a method, I’ll follow this structure.
Now if I have a method called
uploadData, which takes one parameter,data, is it still necessary to give this parameter a description?I realize necessary is kind of subjective in this case, but I’m curious as to what the general consensus is. For the time being I’ve been giving them all descriptions just to keep the consistency of the comments, but it does seem like it’s a very unneeded.
If it makes any difference, the languages I use are Javascript, Java and PHP.
0
The fact that the only parameter to an
uploadfunction is to do with the upload data is not noteworthy. What is worth mentioning is e.g. what format this is in (is it a String giving the name of a local file? a string constituting the data itself? a byte stream?), what restrictions it is subject to (unlimited? no more than 10MB? only 10 per day?), whether all of the values technically allowed by the type are okay (is NULL okay? is the empty array okay? does it have to be a valid UTF8 byte sequence?), etc.If all of these issues are obviously clear to any caller of the method (e.g. if the parameter is a specifically constructed upload object which ensures that only valid data can go in), then go ahead and leave the parameter undocumented. But often it turns out there are additional preconditions, and it is almost always a good idea to make these explicit.
2
I only describe parameters when I’m actually providing the reader with information. The definition of information is “adding to someone’s knowledge”. If the description is not adding to someone’s knowledge, then it is not information and I leave it out.
Also Martin Fowler says if you need to add a comment, you probably need to use a better name for the parameter. That should apply to Javadoc too.
1
Filed under: softwareengineering - @ 23:04
Thẻ: comments
« Breaking a function into smaller ones is great… except for what about code-folding? [duplicate] ⇐ More Pages ⇒ Why do IoC containers provide public Resolve method(s)? »