Re: gEDA-dev: Good software engineering practices for gEDA

[Peter Clifton <pcjc2-at-NOSPAMcam_dot_ac_dot_uk>]

Dear all,

I hope I can contribute something useful here. I'm not sure I have a
"point", but if you like, read some of my ramblings below ;)


On Mon, 2007-05-28 at 00:11 +0200, Ivan Stankovic wrote:
> On Sun, May 27, 2007 at 07:45:13PM +0100, Peter TB Brett wrote:
> > On Sunday 27 May 2007 19:00:08 Ivan Stankovic wrote:
 
> > It would be very nice to have a general mechanism for hooking onto events like 
> > exiting gschem, in case it's needed for work in the future.  In addition, 
> > it's very clear to the person reading the code *exactly* when and where the 
> > hook will be called, which is actually very important.
> 
> Alright, that makes sense. But I have no experience with Scheme and
> don't know how to interface it with C, which means I would be a bad
> candidate to do it. If you're willing to do this, I would be happy to
> amend my patch. 

Adding a me too here, I don't particularly like scheme (or guile), but I
see its purpose. I'm looking to add some features soon, and will attempt
to do so by providing scheme hooks.

Please don't get the impression we are all masters of scheme, as that
certainly isn't the case. (In my example anyway).

> I completely agree with you here, and everything what you said below. I myself 
> consider some of my code ugly and wrongly designed. However, let me point out
> several things. 

Often these are things we only see by implementing code, getting
feedback and with the benefit of hindsight. There are pieces of the
existing code-base which could do with updating, true - and various
people are working on doing so.

There are a few problems though, its lots of work for no outwardly
visible effect other than the inevitable introduction of bugs. This is
why changes like your work to save dialog positions and make a recent
files menu are important. They deliver great new features which persuade
people to upgrade, and do get the code tested. In essence, its changes
like yours people want to see.

I've been playing with some GUI stuff myself recently as it makes a nice
change in the challenges offered. I'm keen gEDA and PCB are more
accessible to new users, and have been looking at what can be improved.

> Firstly, I'm a newcomer to gEDA development so I really don't have the 
> confidence it takes to do major changes to the code base, like your component 
> library changes, for example. Keep in mind, I'm still getting familiar
> with the code. Second, gEDA choosing Scheme for an extension language
> means I can't touch the code in many places since I don't have any
> Scheme experience.

We've not got a great deal of head-start on you, probably not even a
year, so I certainly won't pretend to have all the answers. As I said
above, I'm not a scheme fan, but it does seem to serve its purpose. Ales
may be able to guide you through how various bits work, and I'll try to
help where I can (and its not "the blind leading the blind").

> Third, looking around gschem code I'm not really impressed by the code 
> quality; grepping for '#if 0' ends up with around 80 matches (that's for 
> gschem alone!).

Sounds like a good project ;) Some of them are obsolete debug code (and
can be removed), some are old unused code (should be removed), and
occasionally you see a piece of unused code which might be useful - just
not yet. I've no idea what we should do with those cases.

> There are also design issues that desperately need fixing 
> (I'm currently looking at status bar message implementation -- i_basic.c 
> obviously needs major cleanup). There are even functions that are just
> sitting there, without obvious usage. With code like that, it really is
> hard to do something clean and well designed -- you just have to put put 
> up with what's already there. Unless, of course, you're willing to
> redesign/reimplement big chunks of code, and this gets me back to the
> first point.

Yes, indeed there are bits which need cleaning up, and whilst it makes
it a lot harder, it is possible to clean as we go to avoid perpetuating
the clutter.

On the other hand, sometimes we must accept the "quick" solution, where
we recognise it - and what would be the ideal solution, in order to make
the code work. Perhaps we should make a Wiki page of code we've "tripped
over" that wants attention though.

For brand new code / functionality, showing the commitment to get these
things crafted well is a major step towards it being accepted into the
code-base, and demonstrates that the author may be willing to look after
any bugs in the future.

I had mixed feelings with our latest work Ivan, I like the simplicity of
your original approach (calling the positioning functions after creating
a dialog), the GschemDialog was harder I'd envisaged.

On the other hand, adding a new dialog only now requires subclassing
GschemDialog to get the positioning functionality, and that was the
clincher for me. Far too much of the existing code requires you to
"remember to zoom extents after doing x,y,z" for example, and we should
avoid adding more. As a side benefit, we reduced the number of GtkDialog
subclasses which implement the "TOPLEVEL" property.

> Fourth, and this is probably the most important point, I consider
> gEDA development (somewhat) slow. Now, I understand there is obvious lack
> of developers and existing ones don't have much time to spend. But I
> really don't want to make major changes and then maintain them in my
> own private branch for a possibly long period of time. Rather, I would
> like to do incremental, self-contained patches that get tested well
> and applied reasonably quick (here I must thank you and Peter Clifton
> for all the help with my patches so far). 

I guess its slow for a number of reasons. Yes, a lack of developers, and
other commitments, but it also reflects on the complexity of the code.
Adding new features often requires the existing code to be understood.
refactored and tested, which can be a huge task for the most mechanistic
changes.

Maintaining private branches is a pain. I did it with "noscreen", and
would certainly leaning towards quicker application of small changes
now. It allows other developers to keep on with things, and gives your
code the benefit of wider testing.

BUT: for a given task, the overall progress might be slower. I don't
think I could have written "noscreen" in the order I finally applied it,
I needed to see where it was going.

> Currently, I think the way development here works is: someone has some
> changes ready, requests testing the relevant patches, few people
> check that things go well, the code gets merged and then Ales makes a
> new release.

There is a period of testing and stabilisation before the release, but
essentially you're correct.

> This is all fine, but I'd love to see more users come
> and test development features, since sometimes (often?) a bug is found only
> after the release. When you see more users testing your feature, you
> also have a way to tell if the feature is useful to others, not just
> for yourself.

Its a difficult problem. I don't think many of the developers use gEDA
in their day-jobs. More bugs I've found have been during testing my own
code, than using gschem for work!

Users must be compelled to test beta releases by the promise of killer
features. No user really cares about testing back-end refactoring. Add
to this the pain of installing new versions (often unavailable in any
distro's main repositories), and we see why the uptake is slow.

> And this also tells you if you're adding bloat to the
> code (more on that below).

My ideal patch a) fixes bugs  b) Does so whilst reducing the line-count
(So long as its not a cheating reduction of line-count such as skimping
on comments!) Line count of new features in new files isn't so important
I don't think, but certainly a lot of existing stuff can be simplified.
Complexity breeds bugs!

> Lastly, I think switching main SCM system from CVS to git would really benefit 
> us all (come on people, git isn't any harder to grasp than CVS).

A contentious point there, and whilst some might love git, others would
hate it. I like git, and continue to use a tracker of CVS to base my
changes on. We don't necessarily need to move to git to keep such a
work-flow if we have a decent tracker. I'm therefore not strongly in
favour of switching, but would support a move if it were made.

[snip]

> > Making sure that current developers' time is well 
> > spent, and attracting new developers to the project, both require the code 
> > base to evolve in ways that ensure that not only does code do what you expect 
> > it to, but also that new features and capabilities added are designed in as 
> > generally useful way as sensibly possible.
> 
> Ever heard of overengineering? 
> Also, "perfect is the enemy of good", or something like that?

I see traits of this in gEDA and gnucap development sometimes (to name
two). In some areas, lots of design, little code. Unfortunately, without
some design vision, we can lose track of the end goal.

Peter Brett and I have spent a lot of time working on data-structures,
and possible refactoring ideas, entering into discussion on these lists,
the Wiki and trying to get an overall idea of direction.

Recognising that we can't just implement such plans overnight, (and
trying to avoid the trap you mention) we're working on both incremental
changes which help to tidy up parts of the code, and user-visible
features which help keep people interested in new versions. The long
term goals are still present of course.

Perhaps some sort of road-map which all the devs can contribute to is in
order?

[snip]

> > Please don't take this criticism to personally; it's something I think many 
> > people need to think about, not just you (or me).  It's been brewing in my 
> > mind for the last few weeks, and has only really bubbled to the surface now.
> 
> This also applies to me and this mail. Don't take this personally.

I've made a lot of friends working on gEDA, and I enjoy spending my free
time contributing. Hopefully its a rewarding experience for all of the
developers (it must be, or they wouldn't do it).

Part of the reward I get is learning. Working on gEDA has given me a
great range of coding experience, and access to the wisdom of many
talented individuals. No-one is always "right", and feedback (+ve or
-ve) is part of the process.

Sorry for the ramble.

Kind regards.

-- 
Peter Clifton

Electrical Engineering Division,
Engineering Department,
University of Cambridge,
9, JJ Thomson Avenue,
Cambridge
CB3 0FA

Tel: +44 (0)7729 980173 - (No signal in the lab!)



_______________________________________________
geda-dev mailing list
geda-dev@moria.seul.org
http://www.seul.org/cgi-bin/mailman/listinfo/geda-dev