[Gnumed-devel] Starting a Flame war on nomenclature

[Richard Terry]

I'd like to start a debate on this because I think it is vital and with the 
current state of naming conventions in gnuMed could lead to an impossible to 
maintain project.

The POWER  of modern languages is that we can be descriptive. 

I cut my programming teeth on FORTH. The classic book on forth by Leo Brodie 
'Starting Forth' in reference to readable - maintainable code gave the 
following examples.

FORTH came with a term EMPTY-BUFFERS.

He pointed out how easy it was - and how the tendency was to use the power of 
FORTH to define the word:

        : EB    EMPTY-BUFFERS;

and to then use that throughout the code, which then becomes essentially 
UNREADABLE to anyone else but the programmer.

So, he extolled - 'Be proud to type 'EMPTY-BUFFERS'.

This set the tone for my entire programming career, and all my subroutines are 
properly named in my vb progams  eg

sub vaccination_getdetails_for_patient
sub vaccination_savedetails_for_patient
sub vaccination_get_vaccinationlist
sub vaccination_get_overdue vaccines etc etc etc

Not so in gnumed, and th ID_PUP is a classic. Ian Haywood in response to my 
email said this was a hangover from C++ meaning constants. You say it refers 
to a popup.

In fact in all the wxPython demo code the popup id's are idpopID(n) or some 
such, not ID_PUP

I name my popup ids ID_popup_AddPatientPhoto (not ID_popup10) etc

Similarly, I think the database table and function names are less than 
optimal, but I"m on a little flakey ground here so I'll quit whilst I'm ahead 
and leave that debate until such time as I've really looked into it.

So I would plead!!!! for long names and readability, if only so that others 
trying to help can actually understand what the routines are all about.

As to the rest of the _RoutineName explanations, thanks - now I understand the 
reason for that I'll adhere to the convention.

Regards

richard


On Thu, 19 Aug 2004 10:58 pm, Karsten Hilbert wrote:
> > So as I can improve my nomenclature, can you explain why the use of:
>
> When I review code I almost subconsciously change things to
> the coding style I am used to. It isn't necessarly better but
> helps *me* read/understand the code faster and safer.
>
> >  ID_PUP (instead of just ID_SOMETHING)
>
> ID_ : is customary in wxPython for action IDs
> PUP : you used "Popup" which I found too verbose
>
> > and the underscore  in terms such as:
> >
> > _on_ExportPhoto
>
> A "private" method not part of the normal API. Should be two
> underscore (__) but I am not sure whether that will break at
> some point. Difference:
>
> a_module._something will always be a_module._something. It will
> just not be exported when
>     from a_module import *
> is done. So, private in a sense.
>
> a_module.__a_module will internally be treated as
> a_module._a_module_something. Eg, it isn't easily callable
> directly (one would have to mangle the name manually).
>
> Now, _on_ExportPhoto() is an internal method (an event
> handler) - not part of the API - so "_*". However, I am not so
> sure about using __* since I don't know whether the namespace
> mangling will be done right when the event handler is called
> by the wxPython framework (eg from out-of-namespace). I didn't
> muck around with the "ExportPhoto" part as that was your own
> suggestion. Personally, I prefer export_photo but that's a
> matter of taste, I suppose.
>
> > That way if I understand I will do it as I go and not waste your time
> > having to fix my code.
>
> You can adopt it but I am not enforcing that.
>
> > Also I'll try and remember the underscore bracketed texts which from
> > memory is
>
> thanks
>
> > to allow translation into other languages
>
> correct
>
> > Pretty booked out today -
> > will have about 40 + patients so won't get to it till tonight I suspect.
>
> Don't rush.
>
> > Thanks again for your patience with my learning - but I'm getting there.
>
> Welcome.
>
> Karsten