1 class = 1 file?

Hi,

we have currently added a stream wrapper class for the CSV
DataSource 
driver for Structures_DataGrid. This class is used only for
internal 
purposes and won't be used by any user script, and it would
therefore 
make sense to put this class into the CSV.php file together
with the 
Structures_DataGrid_DataSource_CSV class.

I remember a "1 class = 1 file" rule, but can't
find anything about it 
in the manual. Do we really have this rule? Can somebody
point me to it?

Regards,
Mark

-- 
http://www.markwiesemann.
eu

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Am Sat, 12 May 2007 12:17:39 +0200 schrieb Mark Wiesemann:

I don't know if we have that rule, but PEAR.php itself has
two classes
in one file. But this might be an exception. 

If it is just for internal purpose it should be okay to
include into one
file.



> Hi,
> 
> we have currently added a stream wrapper class for the
CSV DataSource
> driver for Structures_DataGrid. This class is used only
for internal
> purposes and won't be used by any user script, and it
would therefore
> make sense to put this class into the CSV.php file
together with the
> Structures_DataGrid_DataSource_CSV class.
> 
> I remember a "1 class = 1 file" rule, but
can't find anything about it
> in the manual. Do we really have this rule? Can
somebody point me to it?
> 
> Regards,
> Mark
>

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

David Soria Parra wrote:

> If it is just for internal purpose it should be okay to
include into one
> file.

There is no rule that mandates one class per file really.
Personally I 
have always gone by the rule 1 file file per public class.

regards,
Lukas

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Hi,

Lukas Kahwe Smith wrote:
> David Soria Parra wrote:
> 
>> If it is just for internal purpose it should be
okay to include into one
>> file.
> 
> There is no rule that mandates one class per file
really. Personally I 
> have always gone by the rule 1 file file per public
class.

Yes, this makes sense, and this was also what we were
thinking about.
Thanks for the quick replies.

Regards,
Mark

-- 
http://www.markwiesemann.
eu

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

On 5/12/07, Mark Wiesemann <wiesemannphp.net> wrote:
> Hi,
>
> Lukas Kahwe Smith wrote:
> > David Soria Parra wrote:
> >
> >> If it is just for internal purpose it should
be okay to include into one
> >> file.
> >
> > There is no rule that mandates one class per file
really. Personally I
> > have always gone by the rule 1 file file per
public class.
>
> Yes, this makes sense, and this was also what we were
thinking about.
> Thanks for the quick replies.

I thought I read this somewhere in the CS when I started
working on my
package. I also remember someone reminded me to put my
Exception into
a seperate file. Maybe that was even you, Mark? 

IMO and for clarity, it's one class per file. Having too
many
exceptions to the rule just weakens the
"standard". And maybe - if
it's not hidden somewhere already - this should be added to
the docs.

Cheers,
Till

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Hi,

till wrote:
> I thought I read this somewhere in the CS when I
started working on my
> package. I also remember someone reminded me to put my
Exception into
> a seperate file. Maybe that was even you, Mark? 

Right, it was me and it was the (non-existing) rule that I
thought about.

> IMO and for clarity, it's one class per file. Having
too many
> exceptions to the rule just weakens the
"standard". And maybe - if
> it's not hidden somewhere already - this should be
added to the docs.

Well, the rule Lukas, David and (later also) I were talking
about makes 
sense IMHO. Only internally used classes would be put
together with 
other classes, public classes would still go into new files.
Exception 
classes are public and used by user code, and would
therefore also go 
into a new file.

If you want to have a written rule somewhere in the docs,
you should 
send an email to the PEAR Group. Adding a short paragraph to
the docs 
would be easy, but there needs to be a decision about the
rule first.

Regards,
Mark

-- 
http://www.markwiesemann.
eu

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Mark Wiesemann wrote:
>> IMO and for clarity, it's one class per file.
Having too many
>> exceptions to the rule just weakens the
"standard". And maybe - if
>> it's not hidden somewhere already - this should be
added to the docs.
> Well, the rule Lukas, David and (later also) I were
talking about 
> makes sense IMHO. Only internally used classes would be
put together 
> with other classes, public classes would still go into
new files. 
> Exception classes are public and used by user code, and
would 
> therefore also go into a new file.

If a rule like this were to be introduced (and I'd really
love to see 
something solid in the standards) then we'd need to have
some way of 
determining if a class is internal so that we can ensure
that the 
standard is being followed. In my experience a standard that
is not 
enforced, or hard to enforce, is going to be ignored.

I'd actually vote for one class per file no matter how the
class is 
intended for use at the time of release. I think it's a
clearer standard 
that is easier to follow because the developer doesn't need
to decide if 
the rule applies to them. Plus, you never know how your code
is going to 
be used in the future. Maybe those internal classes will be
extended by 
someone else, in which case they become public without your
knowledge.

Greg

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Hey,

On 5/13/07, Mark Wiesemann <wiesemannphp.net> wrote:
> till wrote:
> > I thought I read this somewhere in the CS when I
started working on my
> > package. I also remember someone reminded me to
put my Exception into
> > a seperate file. Maybe that was even you, Mark?

>
> Right, it was me and it was the (non-existing) rule
that I thought about.
>
> > IMO and for clarity, it's one class per file.
Having too many
> > exceptions to the rule just weakens the
"standard". And maybe - if
> > it's not hidden somewhere already - this should be
added to the docs.
>
> Well, the rule Lukas, David and (later also) I were
talking about makes
> sense IMHO. Only internally used classes would be put
together with
> other classes, public classes would still go into new
files. Exception
> classes are public and used by user code, and would
therefore also go
> into a new file.
>
> If you want to have a written rule somewhere in the
docs, you should
> send an email to the PEAR Group. Adding a short
paragraph to the docs
> would be easy, but there needs to be a decision about
the rule first.

Don't get me wrong. I was not trying to bust on you. 

In general I am lazy and I tend to do all sorts of things
when people
don't look (= classes are only used internally) and because
I know
that I try to enforce rules on myself, my code and
development which
essentially improves whatever the outcome is, or whereever
it is used.

So instead of saying "this is internal", I am
instead for one rule
which is applied everywhere, as opposed a lot of if's and
when's.

Till

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

On 5/13/07, till <klimponggmail.com> wrote:
> Hey,
>
> On 5/13/07, Mark Wiesemann <wiesemannphp.net> wrote:
> > till wrote:
> > > I thought I read this somewhere in the CS
when I started working on my
> > > package. I also remember someone reminded me
to put my Exception into
> > > a seperate file. Maybe that was even you,
Mark? 
> >
> > Right, it was me and it was the (non-existing)
rule that I thought about.
> >
> > > IMO and for clarity, it's one class per file.
Having too many
> > > exceptions to the rule just weakens the
"standard". And maybe - if
> > > it's not hidden somewhere already - this
should be added to the docs.
> >
> > Well, the rule Lukas, David and (later also) I
were talking about makes
> > sense IMHO. Only internally used classes would be
put together with
> > other classes, public classes would still go into
new files. Exception
> > classes are public and used by user code, and
would therefore also go
> > into a new file.
> >
> > If you want to have a written rule somewhere in
the docs, you should
> > send an email to the PEAR Group. Adding a short
paragraph to the docs
> > would be easy, but there needs to be a decision
about the rule first.
>
> Don't get me wrong. I was not trying to bust on you.

>
> In general I am lazy and I tend to do all sorts of
things when people
> don't look (= classes are only used internally) and
because I know
> that I try to enforce rules on myself, my code and
development which
> essentially improves whatever the outcome is, or
whereever it is used.
>
> So instead of saying "this is internal", I am
instead for one rule
> which is applied everywhere, as opposed a lot of if's
and when's.
>
> Till
>
> --
> PEAR Development Mailing List (http://pear.php.net/)
> To unsubscribe, visit: http://www.php.net/unsub
.php
>
>

I could easily see one exception in that 1 class per file
rule though.
Excepetions for instance..

<?php

class MyNewException extends Exception { }

class MyEvenNewerException extends MyNewException { }

class OtherException extends Exception { }

class PackageException extends PEAR_Exception { }

?>

Don't get me wrong, but php itself (not talking about
caching) is not
*fast* at reading multiple includes. Doing one include where
all the
execptions are is (imo) a gain of speed after many includes
(instead
of doing require 'exceptionone.php' , require
'exceptiontwo.php', ....
Having one file called for instance Exceptions or better
yet
Package_Execptions.php will be an easy gain of speed in
general.

Anyhoo, I would also be in favor of seeing something like
this in the
coding standards (which we are re-defining atm)

-- 
David Coallier,
Founder & Software Architect,
Agora Production (http://agoraproduction.com
)
51.42.06.70.18

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php