Hi Timour,
On 4/11/10 12:39 AM, Timour Katchaounov wrote:
> Guilhem, guys,
>
> I'd say, enough theoretical talk. Could each proponent
> of a specific method of commenting pick some class, and
> send to the list a sample with comments for both the
> interface and implementation of few class members.
> Such an example should contain a complete meaningful
> description, not just a formal description of parameters
> and results.
Besides Monty, I think everybody else is in agreement.
> Having such examples would make it much clearer to everyone
> who means what, and will hopefully make it easier to conclude
> what are the pros and cons of each approach and come to a
> decision.
A C example:
tennis.h:
/**
Strike the ball with a backhand shot.
@param direction Direction of the stroke (where ball goes).
@param hand Whether the stroke is one-handed or two-handed.
@param topspin Forward rotation applied to the ball.
@remark A two-handed backhand is more accurate and imparts
topspin better. A one-handed backhand allows greater
reach with much pace and penetration.
@retval TRUE You lose.
@retval FALSE Ball has hit the court.
*/
bool throw_backhand(type direction, type hand, type topspin);
tennis.c:
/**
@details A backhand starts with the back of the hand facing
in the direction of the stroke, typically starting with the
arm crossing the body. They keys of a backhands are: footwork,
shoulder turn, racket preparation and follow through.
@return Whether the ball has landed within court limits.
*/
bool throw_backhand(type direction, type hand, type topspin)
{
type racket_data;
prepare_foot();
turn_shoulder();
racket_data = prepare_racket(hand, topspin);
return strike_ball(racket_data, direction);
}
> Also, it would be great if someone could summarize what are
> the suggestions, and what are the pros an cons. (Tor?) Otherwise
> this discussion can go on forever.
I think there is really just one suggestion. In a nutshell, document
interface in headers, document implementation in source file.
Regards,
Davi
