kicad-developers team mailing list archive

[Andrew Lutsenko <anlutsenko@xxxxxxxxx>]

I'm sorry but I disagree with many things here

On Sat, Sep 1, 2018 at 2:13 AM Carsten Schoenert <c.schoenert@xxxxxxxxxxx>
wrote:

> Am 01.09.18 um 10:51 schrieb Andrew Lutsenko:
> > My test is trivial (create a model with some settings, add it to
> footprint,
> > try to read it back).
>
> Sure the tests are simple, but given there are mostly a dozen of them in
> the end count all the single amount of time for getting in touch with
> the functions/tests ... it costs a lot of other peoples development time
> again and again which is in my eyes just burning time on the wrong side.
>
> And you have mostly written above the minimal needed docstring already.
> How much time have you spend to write this btw. :)
>

I have written above what the code does, that is not a good docstring, that
is duplication of information.
It takes less than 10 seconds to read what happens in the test. And it
takes 1 second to read test function name, which is descriptive enough to
explain what is this test for.

I am big proponent of making code readable foremost and assisting it with
comments when needed. Not commenting everywhere for the sake of differently
colored text that adds no information.


> As written, I'd like to see ... this doesn't insist it's a needed thing.
> This decision is done if, by the members of the project.
>
> So far I can tell I'm always wasting a lot of time in other projects to
> understand how the original programmer wanted to use the various
> functions and how they work. Documenting functions isn't nice to have,
> it's a needed policy for me to work together efficiently today in my
> opinion.
>

I agree that documenting functions (specifically interfaces) is necessary
so that you don't have to read the implementation when you are trying to
call the function.
If you looked at my patch I have not added any functions. And you would
never call a unit test method.


> > Fixing other tests is outside of scope of this change.
>
> I haven't written you need to fix or document other tests. To say I'm
> not responsible for other parts of the source isn't the way FOSS
> working, FOSS is working because mostly all feel responsible for 'their'
> project.


That's idealistic view of the world. In reality there is always group of
core devs/maintainers/committers who are actually responsible (to some
degree) and the rest are just contributors.
Projects without such core group go exactly nowhere really fast.

In the end it does not matter what you or I are proponents of. If KiCad
committers say there is a policy to have docstrings on all unit tests I'll
do it, no questions asked. In absence of such policy I follow my own policy
which is: follow established convention in projects that I don't own, do it
like I would do it in my own project if there is no established convention.

Regards,
Andrew