[Gimp-developer] neue Hackordnung

[gg at catking.net]

Hi,

the GIMP is intended to be a collaborative project and I often see  
comments lamenting the lack of contributions from outside the core team.

I think one cause of this is the accessibility of the code.

I have made some minor contributions with the time I have been able to  
contribute but 95% of that time and effort has been largely wasted trying  
to get to grips with illegible, cryptic code.

Now this is my personal experience that I'm feeding back not a personal  
attack on anyone's individual work so let's avoid defensive rebutals and  
flames. I may be alone in this opinion or there may be may others who have  
looked at contributing and just dropped the idea as being too much work. I  
could have achieved a lot more if the code was more maintainable.


The state of the code base is probably typical of a large project that has  
evolved and grown over time from a small personal project. That's just the  
way it is , what I am hoping to put forward are some suggestions to  
improve coding style that will eventually open the possibility of getting  
more contributions.


Right , that's the preamble, here's the crux of it. Again anything I cite  
as an example is just that , not an attack on anyone who may recognise it  
as thier code.


MAKE CODE READABLE:

please, make code readable with explicit variable names and named  
constants. Lines like the following are very economical on file size but  
very wasteful on human time for anyone who did not write the code:

dv = du + w[i];

looks like it came straight of a page of math text book on matrix algebra  
(and probably did). But once out of that context it becomes meaningless.

We might as well be working in assemble not in a high level language. Now  
I have to start mentally decoding what the whole function ( more likely  
the whole file ) is doing and maintain a mental note of what all these  
anonimous variables represent.

delta_x = delta_y + ceoff[i];

with code like that I dont have to read the file to have half an idea what  
the line about.



Another classic which seems to purvey a whole rafts of gimp core code it a  
variable called "byte".

Oddly enough it's not even a byte length variable it's a gint. Sometimes  
it's called bytes or even int and by the time I've chased it back through  
about 10 function calles spread over 3 files I find that in fact it refers  
to PixelRegion.bytes_per_pixel or similar.

Imagine the time that wastes for someone new to the code , it's like a  
paper chase to find the meaning of one variable that could have had a  
clear explicit name I could have understood in the line in which it  
occured. That one was a particualarly devious one to trace but the  
situation somewhat typical.

[quote="Hackordnung"]One goal of GIMP development is to make the GIMP code  
more readable
and understandable. Please help us to achieve this goal by cleaning up
the present code and make sure that all new code follows the coding
guidelines. [/quote]

I recently submitted a patch were I had cleaned up the code and renamed  
this bytes_pp , this oddly met with some resistance and finally got  
accepted as bpp. Fine it's a great improvement, although I was a bit  
dismayed that this sort of change needs debating.


I admit I have written a lot of terse code like this myself in the past  
but only in one-man projects, this really does not fit in a open-source  
context, especially if the project is looking for outside help.


ALLOW LONGER LINES:

Longer names make longer lines. Especially if comments are added. Another  
patch I submitted recently got the comment truncated to the point were it  
was misleading rather then helpful just because it went a few chars over  
the manditory line limit.

I think the rigid coding guide of 80 chars should be re-evaluted.

I started programming on punch cards in around 1980, IIRC we had 80 char  
lines even then, a quarter century ago. My first home computer that  
displayed on a tele had 80 chars. Do we still need to be that  
conservative? I'm against obseleting older kit unnecesarily but does  
anyone working on coding and running gimp not have the width to display  
more than 80 chars? Maybe 120 chars? Comments?


SUMMARY:

In short anyone wishing to contribute will have finite time available. If  
code readablility is an obstacle many will not get invovled. The time  
available to those that do will be largely wasted decrypting the code  
before being productive.


If the idea gets a favourable reception I will submit a short text for  
inclusion in Hackordnung advising on readability and variable naming.  
Current guidelines seem mainly restricted to defining format.


regards, gg