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

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
>

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

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

On 5/12/07, Mark Wiesemann <wiesemann@php.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

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

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

Hey,

On 5/13/07, Mark Wiesemann <wiesemann@php.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

On 5/13/07, till <klimpong@gmail.com> wrote:
> Hey,
>
> On 5/13/07, Mark Wiesemann <wiesemann@php.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