[compiz] Zoom plugin changes

[Kristian Lyngstøl]

On 5/31/07, Mike Dransfield <mike at blueroot.co.uk> wrote:
> Kristian Lyngstøl wrote:
> > I posted a few weeks ago that I was going to be working on zoom over
> > the summer to improve the accessibility, and I have already begun to
> > do that. Every step of the way I have made frequent commits to
> > opencompositing.org and described the progress in my blog.
> >
> > I asked for information about what your (David) plans was, you thanked
> > me for informing me on what I was going to work on and said you'd get
> > back to me. You never did.
> >
> > Now today you commit "11fe37b7673b15e5cbd4be21759311087d9d8694" which
> > introduce major changes to the zoom plugin. You did NOT give a heads
> > up on this, even though you should have known I was working on this.
> >
>
> To be fair he did mention that he was going to add
> this functionality months ago, it was also demonstrated
> at brainshare recently (before your initial email).
>
> Also your email (from what I understand) just related to
> orca integration and input redirection, it didn't seem to have
> anything to do with todays changes.

I asked for an explanation of the features David wanted. He said he
would get back to me. He didn't. Then he drops a big diff. My work
will use at-spi but there were other important things to consider too.
The diff is pretty much a total rewrite of the original which I have
based my work on.

> Also from what I understand, you have forked zoom.c which
> lost all the git history?  If this is the case then you should
> have branched it so that these changes would be merged. I
> dont think they impact your changes, do they?

My point here is twofold:

1. I informed that I would work on zoom and requested information on
it. David confirmed, and posted that he would get back to me.
2. Our users now have to choose between two different feature sets.

As for if it should be a branch or not; maybe so. I'll have no
problems re-playing my diffs to retain the history. I'm prepared to do
that extra work, as it's my own folly for not keeping the history.
This is sort of beside the point here.

> > When you are going to make changes and people have already told you
> > they are working on that code, you have to actually communicate with
> > them, not drop a 1k diff on them. It's not just your time that matters
> > here, but ours too. This is not how people are supposed to co-operate.
> >
> > And also, when you write something, you have to document it.
> >
>
> The question of documentation was discussed very recently
> (and before that too).
>
> Davids position is that HE is not prepared to spend a lot of time
> documenting things because there is a good chance his
> efforts will be wasted if the code changes, personally I'd rather
> he spent time coding rather than documenting.  Someone else
> could document things.

It takes little to no time to document your own code, but it takes a
lot of time to document someone else's code.

It is the individual developers responsibility to document their OWN
code. This helps the community at large because if you spend 1% of
your time documenting, the time save in the other end is huge.

By not documenting the code, it forces other people to reverse
engineer his code when they want to work on it. A few comments on each
function is the difference between using 15 minutes to understand the
code, and an HOUR and 15 minutes. And then you multiply by the number
of readers.

> That does not stop anyone from submitting patches to document
> certain functions which might not be clear.  I did exactly that a
> few weeks ago.

Should not be necessary. It does not take a lot of time to document
your own code, and it is a sign of a good programmer. I know projects
that will just say "sorry, try again." if you attempt to submit
undocumented code. Not documenting your code is two things, whether
that is the intent or not:

- Lazy.
- A slap in the face of the other developers.

> > A few lines for each function, explaining what it does. You don't have
> > to explain how or why, just WHAT. This is a common practice that I
> > should NOT have to explain to an experience developer.
> >
>
> Its not common developer practice to document each
> function.  Most people do not seem to have much problem
> understanding whats what, and David is always prepared
> to answer questions.  The documentation is by example at
> the moment, I have 3 example plugins, the helloworld one
> is documented as well as I can, and I try to keep it up to
> date.

... Your help plugins are a great help for new Compiz developers and
all though I have not used your work on them myself (By the time you
wrote them, I didn't need them), I am grateful for the work you've put
into them. However, this doesn't void the need for documenting the
rest of the code. And it does not help me at all.

And I doubt most people know up from down in half of the code David
has written. Sure, you can read the individual parts, but to trace the
flow of the code, to know how it all fits together, that requires more
than just reading each code file line by line.

As it so happens, I have spent a lot of time tracing the execution of
compiz step by step, and probably know how core works better than
most. And this knowledge has just underlined the need for
documentation.

> > Please document your changes to the zoom plugin properly so our USERS
> > don't have to choose between two different feature sets when they want
> > to zoom. Because this is about the users, not my pride.
> >
>
> If you understood the original zoom code enough to
> make an enhanced version of it then it should be easy
> to understand the new changes, they seem to be reducing
> code and increasing readability to my untrained eyes.

Of course I understand it. I know C, it's not a matter of whether or
not I understand it. It's a matter of whether I use 15 minutes or an
hour and 15 minutes to understand the details. Like I said: I don't
expect documentation on why or how a function does what it does, just
what it does.

David: I may have been rude in my original mail because I was fairly
upset, but I still think this deserves attention. We have merged, this
is no longer just "your" project where other people can help you; this
is a project with several developers, not just yourself. You need to
adopt to that, so we don't get into a situation with a lot of
duplicated effort, internal fighting and people walking away because
one person refuse to adopt.

The developers of the Beryl project have accepted a lot of compromises
in your basic design, in the name, in the coding style, in pretty much
everything. I believe it would help not only myself but all developers
if you start documenting your code. And it does not compromise any of
your technical decisions.

We don't ask you to explain how all your code works or why, just what
the basic input and output of a function is. It does not require a lot
of time, and I don't expect you to go over old code (what's done is
done), just please keep this in mind for NEW code.

-- 
Regards,
Kristian