Re: [mantisbt-dev] New coding guidelines

[Victor B. <vb...@gm...>]

I've reviewed the Zend Framework coding conventions and it looks really
good.  Although I hate to change conventions, I'm totally on board with the
fact that to really move to PHP5 and OO, we will need to revise our
standards, and hence, I think to use this one sounds like a good idea.

As for the transition and some other process relating remarks that I had in
mind, here are some comments:

1. Plugin framework - As we change the class names and API files / names, we
will break plugins.  There are areas that are more likely to be used by
plugins than others (e.g. plugin base classes).  We need to brainstorm on
this a little bit to come up with the best course of action.

2. Class Names - The class names depend on the directory structure in ZF.
However, for Mantis, I think it should depend on the components.  For
example, Mantis_Core_Xyz.  This matches the current directory structure, but
if we move core to somewhere else, then it continues to be Mantis_Core_Xyz
since it still remains part of the "core" logical component.

3. SOAP API - Ideally the SOAP API will not be broken by renames to its
methods or structures.  If we want to change to the new standard, we should
consider a compatibility layer.

4. Auto Include - If we are going to use the auto include feature of PHP, we
should verify that the class naming conventions / file names / file location
are as expected.  If would expect that ZF team has already thought of this,
but my suggestion for 2 may break it.  If so, then we should re-think 2.

5. In Place Upgrade - We should update admin/check.php to check for obsolete
file names and surface them to the user.  As we are moving / renaming files,
in place upgrades will cause a big mess.  We should help users to avoid /
fix such mess.

6. Exceptions - Core classes should use exceptions rather than output errors
directly.

7. Model - The model classes should not include any code that prints or
formats output.

8. Unit testing - With a pure model and use of exceptions we should be able
to implement unit tests.

 9. Templates - As we are re-structuring Mantis, we should consider our
plans to move to MVC / templates.
10. Custom Functions - Needs to be re-designed.

11. Build - Implement a build script which runs unit tests, compiles
docbook, pushlishes snapshots, sends emails with failures, etc.

12. Automate the running of the build (e.g. run once a day when there are
checkins).

13. Incremental Approach - We should set clear targets and incrementally
move towards them.  I don't want to create branches that get obsolete and
abandoned.  We can clean up one API at a time, change client code to use it,
implement unit tests, etc.

14. No Framework (for now) - We already have a lot of work as is, I don't
think we should move to ZF as an underlying framework (or any other) for
now.  Obviously if we make a decision to move to a framework like CakePHP
rather than ZF, then following ZF standard is really a waste of time :).

On Mon, Aug 25, 2008 at 5:21 AM, Gianluca Sforna <gi...@gm...> wrote:

> Hi Glenn,
>
> On Sun, Aug 24, 2008 at 4:29 AM, Glenn Henshaw
> <thr...@lo...> wrote:
> > 1) The file naming convention is quite different from what we use now. It
> > seems to be useful (to me) to understand that the file defines API or
> class
> > functions.
>
> IMHO new code should not pollute anymore the global namespace that is,
> all functions should be either static methods ( Class::method() ) or
> regular objects methods: Object->method()
>
> > 2) The function naming convention is missing the API name. This is also
> very
> > useful in locating the function / method source. As we move to OOP, we
> > probably need a convention for object instantiation that refers back to
> the
> > original class name so we can make a similar traceback.
>
> We just need to rethink how we determine this info, for instance:
>
> old convention: string_display_line() -> core/string_api.php
> new convention: class Mantis_String -> core/Mantis/String.php
>
> besides, try guessing where is print_manage_menu() ?
>
> > 3) I like the current variable naming convention that we have that
> > differentiates local, parameter, and global variables. It also helps
> ensure
> > that we know what has global scope.
>
> That naming convention is really useful when you have longer functions
> and you risk to fail remembering where $variable come from.
>
> In the brave new world, I don't think we need to use prefixes because:
>
> 1. global variables (g_) should not exists
> 2. functions should be short enough to make the local/parameter
> distinction useless
>
> However, guidelines says protected and private class members should be
> prefixed with _ for an easier recognition:
>
> http://framework.zend.com/manual/en/coding-standard.naming-conventions.html#coding-standard.naming-conventions.variables
>
> Cheers
>
> Gianluca
>
> -------------------------------------------------------------------------
> This SF.Net email is sponsored by the Moblin Your Move Developer's
> challenge
> Build the coolest Linux based applications with Moblin SDK & win great
> prizes
> Grand prize is a trip for two to an Open Source event anywhere in the world
> http://moblin-contest.org/redirect.php?banner_id=100&url=/
> _______________________________________________
> mantisbt-dev mailing list
> man...@li...
> https://lists.sourceforge.net/lists/listinfo/mantisbt-dev
>