Use a convention to structure your code

Published on and tagged with code  convention  tip

One feature I like in Eclipse is the outline view which shows you the structure (i.e. the variables and methods) of the file you edit and allows you to jump quickly to those code elements (see image).

Outline view

To use this feature efficiently it makes sense to use a convention to structure your code (the example in the image is unstructured hence it is more difficult to find a certain method). And even if your IDE doesn’t provide such a feature it makes sense to follow a convention as it makes your code more cleaner.

The convention I use is simple: first public stuff, then private stuff, both ordered alphabetically. So a CakePHP file may look like:

class A {
    var $a = ...
    var $z = ... 
    var $__a = ...
    var $__z = ...

    function a() {}

    function z() {}

    function __a() {}

    function __z() {}

Especially if you have larger files it helps to avoid that you get a messy code structure. And it doesn’t require any additional effort.

5 comments baked

  • bkuhns

    This is pretty good advice, though I’ve been doing something similar for a while. With cakePHP, I write my controllers with all the public actions first (if there are “admin_” actions, they go after the normal ones), followed by public functions that may be called through requestAction. Finally, any private functions come at the very end. This really helps when jumping around controllers so you know where in the file to look for certain things.

  • brandon

    IMO, I think variables and methods should always be sorted alphabetically. I think this based on how one “reads” source code. Grouping semantically equivalently methods make the source easier to read and especially easier to find.

    The access of those methods (public, private, protected, etc) is ancillary when reading source code and only matters when you are instantiating/extending the object.

    I think we could all benefit from some more defined standards when it comes to naming variables and methods. For instance, “_” and “__” should no longer be used outside PHP4, get/set methods, or even type hinting on variables names.

    On another note, why do you think so many people are still stuck on PHP4? In mid July the PHP Team announced they will no longer release new versions of 4.x at the end of this year and will stop ALL work on by Aug 2008.

  • Mladen Mihajlovic

    You don’t actually need to write the methods in alphabetical order for them to appear in that order in the outline view – there is a button there to sort them.

  • Henrik

    What kind of eclipse setup do u use??

  • cakebaker

    @all: Thanks for your comments!

    @Brandon: I think one reason why many people stay with PHP 4 is that nobody wants to pay to migrate old stuff.

    @Mladen: Yeah, I am aware of this button, but unfortunately it mixes the variables and methods. And that’s something I don’t like ;-)

    @Henrik: Currently I use PDT 1.0 ( together with the Subclipse plug-in.

© daniel hofstetter. Licensed under a Creative Commons License