Re: [Ayttm-devel] Function prototypes in .c files

[Andy]

[Sorry this won't thread nicely - I had to copy the text by hand because I 
didn't receive the email...]

On Tue, 21 Jan 2003, Philip wrote:
> On Tue, 21 Jan 2003, Andy wrote:
> 
> > I don't think this is a very good idea.  The prototype is in the
> > header for a reason and we should be including the header file.  
> > There should be one declaration and one definition of a function.  
> > Not doing this means that there are N declarations floating around
> > which can be a headache to maintain.
> 
> Yeah, I agree in the general case, but the problem here is that just 
> including those two headers in sound.c doubles the size of sound.o.  
> (This doesn't affect the size of the ayttm binary by too much)

I don't understand how including a header can affect the .o size [unless it 
adds some junk for debugging with -g on or includes code?].  Regardless, I 
think when you resort to what you've done it's a symptom of poor design of 
the header files :-)

> The reason I've been trying to remove gtk dependencies from wherever 
> possible is so that we can finally split the gui out of the core and 
> into a module.

Great plan.  I'm all for working towards this.  Then can I have my Qt 
interface? :-)

[snip]
> A few things that I'm looking at to start with are:
> 
> - All header files should be self sufficient.
> If a header contains references to glib stuff, it should include glib 
> and not depend on it being included by all C files that include it or by 
> other headers that it includes.  The same goes for types defined in 

Can you explain this a bit?  Are you saying the opposite of the next point 
here for include files?

> ayttm.  Forward declarations are fine in this regard if the size of the 
> type isn't required.

> - Source files should include all headers that it depends on, but 
> allowing for headers that include other headers. We might have to 
> change this later, but the compiler will help us out there.

I agree - as much as possible header files should be processed once per source 
file [even if they have ifndef guards].
 
> - functions static wherever possible
> To avoid namespace pollution.

Very much agreed.  Global [in the .c file] variables static when possible too.  
This is a big one because not only can the compiler do more with things that 
are static, but it's a good hint to the developer what can be changed locally 
without widespread repercussions.  The whole namespace thing is a mess in 
ayttm.  There seems to be no naming conventions whatsoever [please correct me 
if I'm wrong].

> - types defined only in files that require them
> If a type is required by more than one source file, then the type should 
> go into a header file, else, it should be in the source file.

Strongly agree.

> - Try and strip gtk out of as many headers as possible.
> The reason for this is that many modules that don't require gtk at all 
> (eg: autotrans, notes, etc.) include these headers and become huge.  
> This takes up extra RAM at run time and does slow down loading of 
> modules.

Again header -> file size relation?  Is this a GTK thing?

> I think Andy's working towards some of the same things.  It seems that 
> some of our changes do conflict, so maybe we should discus this through 
> before doing any more.
> 
> Another thing we need to discus is the naming of types.  Some types are 
> typedef'd, some are not, some names are too long and some don't mean 
> what they should.

I think naming in general needs to be discussed.  For example, how do I know 
that a variable called filename is global?  My preference is to use gFileName 
if it's truly a global and sFileName if it's a .c file static global, but any 
way of indicating that we're dealing with a global is again a huge help for 
the developer when modifying something.

Which makes me think of another thing here.  There seems to be an awful lot of 
'magic numbers' in this code.  I think this should be addressed as well.  We 
could also talk about preferring an enum over a bunch of defines....

Cheers,
        Andy