One of the things that I’ve been criticized for (for lack of a better term, I suppose) is that I push object-oriented techniques over procedural programming  in WordPress.

To some degree this is true: I do prefer object-oriented programming, but I don’t think it’s the end-all-be-all of programming paradigms. After all, when building, say, a theme, there’s actually little room for writing object-oriented code.

On top of that, because of the minimum requirements of WordPress, there are a lot of advanced features in PHP that I avoid because I can’t be guaranteed that the end user will have them available on his or her system when they install the plugin.

So, sure, I prefer object-oriented programming, but I certainly don’t aim to make it the utopian programming practice.

That said, there is one aspect of procedural programming that requires some type of convention: private functions.

Private Functions in Procedural Programming

When it comes to writing private functions in procedural programming, it’s really a convulsion of terms because the very nature of procedural programming doesn’t have the idea of function scope; therefore, you can’t really have public or private functions, right?

Helper Functions

Sometimes I also refer to these functions as helpers. You know what I mean: They are functions written to help to run an algorithm on a data, perhaps retrieve some information in a certain format, or make it easier to read (and write) conditional code.

The thing is, they’re really only known by the people working on the codebase – that is, they aren’t, say, covered in any API documentation.

A Tangent on JavaScript

At one point in my career, I was spending a lot of time in JavaScript and I needed some way to indicate what functions were my private helper functions versus those that were meant to be used elsewhere in the codebase.

This is not meant to spark a discussion on creating private functions within the scope of a custom prototype, so I digress on that point.

So to differentiate between the functions that were to be used throughout the code versus those that were not, I’d write something like this:

  • Normal functions: insertAfter( elemBefore, elemAfter )
  • Helper functions: _verifyIsSafe( sEmailAddress )

Easy, right? Prefix an underscore and go on about it.

Now Back To PHP

With that in mind, that’s how I’ve historically been writing functions intended for internal use or as helpers within PHP so that they are easily identified as such.

That is to say, I prefix the functions that are normally helpers with an underscore to show they are meant for internal use only.

It works well for me, but is it the accepted convention?

Am I Missing Something?

I’ll be the first to admit that procedural programming is not the primary way in which I write code (of course, I think that’s evident ;), so I can’t be certain that the above technique is what’s actually used.

As such, I’m asking you guys if I’m missing something or if there is a more common way that developers indicate what are considered helper functions (and aren’t meant to be made, say, publicly aware)?

Category:
Articles
Tags:

Join the conversation! 15 Comments

  1. I prefer the underscore convention for private functions / variables in classes as well.

    With procedural code, there’d have to be some support reason or otherwise to bother since people will likely just use them anyway.

    It’s funny to me that you’ve gotten flack for using / advocating OOP. I would have expected the opposite, if anything.

    • It’s funny to me that you’ve gotten flack for using / advocating OOP. I would have expected the opposite, if anything.

      At this point, nothing surprises me anymore. I’ve caught flak in some form or fashion for whatever position I’ve taken (or not taken) on any given thing in this particular area.

      Just part of it, really.

      I suppose that it’s true in other industries, as well :).

  2. If you had a pure PHP programmer, and they looked at your code could there be some confusion with some of the ‘magic’ functions in PHP and the meaning behind your functions/variables/whatever with one underscore?

    I originally came from a VB6 background (hungarian notation) but have now, for many years, developed in C#, where the convention is to use the _ for private members. As I code daily in C# and SQL (in the day job), and HTML, Javascript & PHP(writing WordPress stuff) I tend to suffer from notation over-stimulation (I was trying to find something that rhymed).

    My philosophy is to be consistent with whatever notation is currently there or be very sheep-like and follow whatever convention seems to be most prevalent within that particular community.

    The point I am failing miserably to get at is, does it matter what convention you use as long as it is consistent within the community/codebase you are working in?

    • If you had a pure PHP programmer, and they looked at your code could there be some confusion with some of the ‘magic’ functions in PHP and the meaning behind your functions/variables/whatever with one underscore?

      There should never be magic in code, in my opinion; however, it’s pretty much all over the place so, you know, nature of the beast and all of that.

      My philosophy is to be consistent with whatever notation is currently there or be very sheep-like and follow whatever convention seems to be most prevalent within that particular community.

      That’s not being a sheep. That’s being a good member of the community especially if the convention is documented somewhere :).

      The point I am failing miserably to get at is, does it matter what convention you use as long as it is consistent within the community/codebase you are working in?

      It matters if it’s documented, IMHO. Otherwise, if you’re able to set the standards, then you (and/or a team) set the standards, and enforce them. That’s how I’ve done it at a previous job.

      That said, there are conventions for some projects like in .NET or in PHP that try to provide standards across the board. It’s worth looking into those.

  3. Python people writing the famous issue tracker Trac http://trac.edgewall.org use this convention. That’s good enough for me!

  4. There is an historical convention for using an underscore prefix for a function name to show it’s private. Any competent developer looking at it should register the fact that it may be “private”. The only way to be sure though is via the definition documentation.

    The correct way would be document the function as @internal. A single tag, that says in one unambiguous word, that this is an internal function.

    The trouble with the underscore prefix, is that it’s not DRY. You’re re-stating at each instance of calling the function that you consider it to be private.

    If you later decide that the function should not be private, you’ve got the underscore duplicated all over your code. It is then either indicating that a public function is private (aka an @api function is @internal), or you’ve got a lot of updates to do.

    If you had marked it as @internal, then you’ve only got the documentation to update in a single place. The code would be easier to read due to fewer symbols littered in it. Each variable then only represents the value assigned to it, not the intended privacy level as well.

    • The only downside to not putting in an underscore is that if you are in a code module and hadn’t looked at the documentation, inline or not, it would not be immediately obvious that the function/variable the developer considered as private is actually private.
      However I think you make a very valid point about using an underscore as not being DRY. I hadn’t considered DRY down to internal variable/function level before but now you mention it’s obvious.
      Of course we all look at docs before we start doing anything ;-S

      • The only downside to not putting in an underscore is that if you are in a code module and hadn’t looked at the documentation, inline or not, it would not be immediately obvious that the function/variable the developer considered as private is actually private.

        This is true, but based on what other commenters have shared, this is a relatively common practice.

        Nonetheless, if that format isn’t documented *somewhere*, then the developers haven’t done such a hot job of maintaining their own project.

        However I think you make a very valid point about using an underscore as not being DRY. I hadn’t considered DRY down to internal variable/function level before but now you mention it’s obvious.

        Agreed. I’d not considered it from a DRY perspective before.

        Of course we all look at docs before we start doing anything ;-S

        Oh, yes. All of us. All the time. No one ever just jumps right in, right? . . . . . . . .

    • There is an historical convention for using an underscore prefix for a function name to show it’s private. Any competent developer looking at it should register the fact that it may be “private”. The only way to be sure though is via the definition documentation.

      I *thought* it was historical, but I didn’t want to be presumptuous. At least it’s nice to know that it’s on the right track :).

      Anyway, yes – it absolutely be documented somewhere.

      The correct way would be document the function as @internal. A single tag, that says in one unambiguous word, that this is an internal function.

      Noted. Love this.

      If you had marked it as @internal, then you’ve only got the documentation to update in a single place. The code would be easier to read due to fewer symbols littered in it. Each variable then only represents the value assigned to it, not the intended privacy level as well.

      Hm. Which now prompts me to wanting to do this over adding a prefix.

      Personally speaking, how do you handle it, Gary?

      • > Personally speaking, how do you handle it, Gary?

        I don’t consider any functions to be private, full stop. I can’t enforce it, so I’d rather refactor the code so that the function potentially becomes re-usable, even if it’s something like a callback for uasort() which is likely to be not re-used in a real situation.

        Take _doing_it_wrong() for instance. That’s supposed to be for internal use only, yet themes and plugins use it anyway. Instead of considering it to be private, it should have been written as a formal way that everyone could use from the outset. To switch it over now would be a pain, due to BC concerns.

        The choice between @internal or an underscore prefix is really the wrong question. The question should be, why do I consider this function to be “private”, and how can I make it “public”.

  5. So maybe having a lot of private functions is a code smell? In my experience I see private functions usually being used as helper functions, in order to keep public functions small and concise. So maybe what should happen is that if you have a lot of private functions they should be refactored out into helper classes with public functions?

    • So maybe having a lot of private functions is a code smell?

      Potentially, yes — though I think a lot of practices have the ability to be a code smell if overused or abused.

      I’m with you, though, in that I usually see them as helper functions, especially within the context of procedural programming. When it comes to OOP, I tend to be a fan of some of the principles of domain-driven design (and thus a domain language) so writing private helpers to make the code more readable really comes in handy.

  6. I’m a little late, but I remembered this post while writing a private function. I use both the underscore convention and the @internal tag, but I take one more measure by putting these functions in a separated file, named something like internal.php. That way, any other developer that is not aware of the convention or is not reading the documentation, at least has a third opportunity to note the private status by looking at the name of the file where the function is located.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.