On 4/13/10 1:53 AM, Michael Widenius wrote:
>
> Hi!
>
>>>>>> "Davi" == Davi Arnaut<Davi.Arnaut@stripped> writes:
>
> Davi> Hi Timour,
> Davi> 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.
>
> Davi> Besides Monty, I think everybody else is in agreement.
>
> Davi, please don't generalise when you don't have all the facts ;)
I'm not generalizing. Timour asked about "each proponent" and I simply
pointed out that at that point of the discussion everybody (that
participated, not the whole world) expect you was in agreement (ie they
were consistent wrt method). I can quote if necessary.
> Not everyone that is coding on MySQL has given their opinion.
> You should assume that those that are silent are voting for keeping
> things as they are...
That's not how it works, otherwise you would be generalizing. Usually,
silence is consent. Also, don't appear to claim something as "bad" if
you are going to do it a few lines below :-)
>>> 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.
>
> Davi> A C example:
>
> Davi> tennis.h:
> Davi> /**
> Davi> Strike the ball with a backhand shot.
>
> Davi> @param direction Direction of the stroke (where ball goes).
> Davi> @param hand Whether the stroke is one-handed or two-handed.
> Davi> @param topspin Forward rotation applied to the ball.
>
> Davi> @remark A two-handed backhand is more accurate and imparts
> Davi> topspin better. A one-handed backhand allows greater
> Davi> reach with much pace and penetration.
>
> Davi> @retval TRUE You lose.
> Davi> @retval FALSE Ball has hit the court.
> Davi> */
> Davi> bool throw_backhand(type direction, type hand, type topspin);
>
> Davi> tennis.c:
>
> Davi> /**
> Davi> @details A backhand starts with the back of the hand facing
> Davi> in the direction of the stroke, typically starting with the
> Davi> arm crossing the body. They keys of a backhands are: footwork,
> Davi> shoulder turn, racket preparation and follow through.
>
> Davi> @return Whether the ball has landed within court limits.
> Davi> */
> Davi> bool throw_backhand(type direction, type hand, type topspin)
> Davi> {
> Davi> type racket_data;
> Davi> prepare_foot();
> Davi> turn_shoulder();
> Davi> racket_data = prepare_racket(hand, topspin);
> Davi> return strike_ball(racket_data, direction);
> Davi> }
>
> What I am talking about is that I want to have all the remarks and
> parameter descriptions also in the .c file. Just because you have
> documented things in the .h file, you shouldn't make the .c file
> harder to read.
It's not harder to use. Jumping to a header to read necessary stuff is
not harder. Perhaps we have different definitions of what is "hard".
"Hard" for me is something that requires a great deal of endurance in
difficult, painful process. A few additional keystrokes is merely a
minor annoyance.
> <cut>
>
> Davi> I think there is really just one suggestion. In a nutshell, document
> Davi> interface in headers, document implementation in source file.
>
> No, there is many suggestions, as this thread has shown.
Expect yours, they all seemed to be the same thing. Precisely, which one
have I missed?
Regards,
Davi Arnaut
