Re: gcs doubt #1

Re: gcs doubt #1

[Marco Gerards]

adrian15 <adrian15@raulete.net> writes:

> Please put a comment on each function saying what the function does,
> what sorts of arguments it gets, and what the possible values of
> arguments mean and are used for.
>
> Is it ok that the search.c and test.c (commands/ folder) do not have any
> of these comments at all?

The currect test.c is a dummy so the `if' expression can be
used/tested.

If you can provide a patch for sourcecode to improve or add comments
in a sane way, I am willing to commit those patches.  Just please
don't make the mistake to add useless comments.

--
Marco

Re: gcs doubt #1

[adrian15]

>> > Please put a comment on each function saying what the function does,
>> > what sorts of arguments it gets, and what the possible values of
>> > arguments mean and are used for.
>> >
>> > Is it ok that the search.c and test.c (commands/ folder) do not have any
>> > of these comments at all?
> 
> The currect test.c is a dummy so the `if' expression can be
> used/tested.
> 
> If you can provide a patch for sourcecode to improve or add comments
> in a sane way, I am willing to commit those patches.  Just please
> don't make the mistake to add useless comments.

An useful comment is one that:
	-Describes a function algorithm
	-Describes what a function does (as a black box)
	-Boot of them ?

adrian15

Re: gcs doubt #1

[Marco Gerards]

adrian15 <adrian15@raulete.net> writes:

>>> > Please put a comment on each function saying what the function does,
>>> > what sorts of arguments it gets, and what the possible values of
>>> > arguments mean and are used for.
>>> >
>>> > Is it ok that the search.c and test.c (commands/ folder) do not have any
>>> > of these comments at all?
>>
>> The currect test.c is a dummy so the `if' expression can be
>> used/tested.
>>
>> If you can provide a patch for sourcecode to improve or add comments
>> in a sane way, I am willing to commit those patches.  Just please
>> don't make the mistake to add useless comments.
>
> An useful comment is one that:
> 	-Describes a function algorithm
> 	-Describes what a function does (as a black box)
> 	-Boot of them ?

Yes, but I oppose to adding obvious comments.  But patches will be
reviewed, so you will learn fast enough what we want :-).

--
Marco

gcs doubt #1

[adrian15]

In the GNU Coding Standards they say in:

5.2 Commenting Your Work

Please put a comment on each function saying what the function does,
what sorts of arguments it gets, and what the possible values of
arguments mean and are used for.


Is it ok that the search.c and test.c (commands/ folder) do not have any
of these comments at all?

You do not comment them at all?
You comment them in another place?
Maybe it's ok with the help description that it is set when you register
a command?
Maybe this is a bug and should be fixed?

adrian15

Re: gcs doubt #1

[adrian15]

>>> If you can provide a patch for sourcecode to improve or add comments
>>> in a sane way, I am willing to commit those patches.  Just please
>>> don't make the mistake to add useless comments.
>> An useful comment is one that:
>> 	-Describes a function algorithm
>> 	-Describes what a function does (as a black box)
>> 	-Boot of them ?
> 
> Yes, but I oppose to adding obvious comments.  But patches will be
> reviewed, so you will learn fast enough what we want :-).

You had to choose one of the three options :).
Well... it doesn't matter. I've understood that I have to send patches
and learn by trial-error.

adrian15