Looking for more information on how to do PHP the right way? Check out PHP: The Right Way

Dylan Bridgman:
Writing highly readable code
Jul 30, 2015 @ 12:29:55

Dylan Bridgman has posted a few helpful tips on writing code that's "highly readable" and easier for both developers inside and outside the project to understand.

We are always told that commenting our code is important. Without comments other developers will not be able to understand what we did and our future selves will recoil in horror when doing maintenance. Readable code, however, is not only about comment text. More importantly it is about the style, structure and naming. If you get into the habit of writing easily readable code, you will actually find yourself writing less comments.

He breaks it up into a few different categories to keep in mind as you're writing your code:

  • the overall style of the code
  • the structure of the application (directories, libraries used, etc)
  • naming conventions for variables, methods and classes

Finally, he talks about comments and how they should fit into the ideas of readable code. He suggests that they should stay as high level as possible and explain the intent of the code, not what the code is doing (yes, there's a difference).

tagged: write readable code tips style structure naming convention comments

Link: https://medium.com/@dylanbr/writing-highly-readable-code-94da94d5d636

Phil Sturgeon:
A Quick Note on PSR Numbering
May 06, 2015 @ 09:41:55

With a lot of talk happening around the PSR-7 HTTP request/response proposal and PSR-4 being the last "official" standard to be posted, some people are wondering what happened to PSR-5 and 6. Phil Sturgeon, a previous member of the PHP-FIG, has posted some clarification to how the PSR process works and where those seemingly missing PSR numbers are at.

The last PSR from the FIG to be sent out into the world, to be used by whoever felt like using it, was PSR-4: Autoloader. Now people are starting to hear about PSR-7, and they’re starting to “lolphp”, wondering what has happened to PSR-5 and PSR-6. [...] This is not like The Neverending Muppet Debate of PHP 6 v PHP 7, despite it being the first though to pop into many peoples heads. Instead, this is down to the Workflow Bylaw I put into place last year.

He goes on to talk about the current workflow stages and how, unlike systems in other languages, the PHP-FIG's process gives proposals a PSR number even before they're published and accepted. He also briefly talks about PSR "nicknames", naming to differentiate between similar proposals and how, despite the need for these names, they're just reference points for conversations more than anything.

tagged: psr7 psr proposal workflow process numbering naming phpfig

Link: https://philsturgeon.uk/php/2015/05/05/psr7-numeric-workflow/

Piotr Pasich:
ClassManager - You shall not pass
Jan 30, 2015 @ 11:42:55

Piotr Pasich has shared some thoughts on naming in his latest post to his site today. In it he talks about one of the "hardest things in computer science" (naming things) and makes some recommendations to help you make naming in your code more effective.

Precise names for classes is notoriously difficult. Done right, it makes code more self-documenting and provides a vocabulary for reasoning about code at a higher level of abstraction. There are a couple simple tips&tricks to make the names more readable: do not abbreviate, do not add any extra informations (underscore, type), avoid single letter prefixes, etc etc.

But what if you already know and use those rules and you still want to improve naming in your code? I assume that you care, you’re not selfish and you think about elses when you write the code. You ask one of the most important question to yourself, during architecture implementation – how the fellow sitting next to will behave while reading the code.

He's broken up the remainder of the post into different sections, each with a high level recommendation and some follow up description:

  • Ask somebody else
  • Does it have a single responsibility you can name?
  • Simple Superclass Name
  • Qualified Subclass Name
  • Adding ‘Interface’ word

He ends with a few names to avoid (like *Manager, *Helper or *Handler) to help prevent ambiguity. He reinforces providing meaning in your naming and making it easier for others to understand what's going on.

tagged: classmanager naming opinion recommendation avoid meaning

Link: http://piotrpasich.com/classmanager-you-shall-not-pass/

Jani Hartikainen:
How to make your code self-documenting?
Dec 02, 2014 @ 09:35:21

In this new post to his site Jani Hartikainen suggests a few things you can do to help make your code "self-documenting" and more readable down the line (or for other developers).

Isn’t it fun to find a comment in code that’s completely out of place and useless? What if you could write fewer comments and still keep the code easy to understand? One of the primary ways to do this is making your code-self documenting. When code is self-documenting, it doesn’t need comments to explain what it does or its purpose, which is great for making the code easier to maintain. As a bonus, with fewer comments, it’s less likely they’ll be crap! In this article, I will show you several ways you can make your code document itself.

He breaks it up into a few different sections, each with some code examples and descriptions:

  • Naming things
  • Extract functions
  • Introducing variables
  • Defining class and module interfaces
  • Code grouping

He finishes up with a few smaller tips including "don't use strange tricks" and "use named constants". What do you think makes for good self-documenting code? Share some of your own thoughts on the post.

tagged: selfdocumenting code examples naming separation extract group

Link: http://codeutopia.net/blog/2014/12/01/how-to-make-your-code-self-documenting/

Phil Sturgeon:
The Neverending Muppet Debate of PHP 6 v PHP 7
Jul 24, 2014 @ 10:18:14

Phil Sturgeon has posted about something he calls the "neverending muppet debate of PHP 6 versus PHP 7. As the PHP language moves forward, the PHP 5.x series is coming to a close. The discussion as started up whether to name it "PHP 6" or "PHP 7" and both sides have their proponents.

There are a few major, important conversations happening in the PHP internals mailing list as we speak: The Facebook lot heading up a specification based off of PHP 5.6 Should phpng be moved into master to be the base of the next major PHP version How can we best go about scalar typehinting? There is also another conversation: Should it be PHP 6 or PHP 7 Wait... what?

He goes on to provide a little context, pointing out that back in 2010 PHP 6 was being slated for release as the next major version of the language (this was around the PHP 5.2 days). Unfortunately, it stalled out and some of what was planned went into PHP 5.3. This didn't stop publishers from releasing books and articles about "PHP 6" though. It's already being put up for a vote with "PHP 7" pulling ahead. Phil also includes more context around the discussions, sharing the main points of each side and snippets from the RFC and mailing list thread currently ongoing.

tagged: debate php6 php7 naming internals rfc version

Link: http://philsturgeon.uk/blog/2014/07/neverending-muppet-debate-of-php-6-v-php-7

Frank de Jonge:
A Case Against Coding Lingo
May 28, 2014 @ 10:54:14

In this new post to Medium Frank de Jonge talks about one of the infamous "two things hard about programming", namely...well, naming things.

The other day I had a small discussion on one of my open-source projects, in this case Flysystem. It was about the smallest thing ever, the name of a method. A method name that was suggested to replace another method name just didn’t feel right to me. It made me wonder why. I came to the conclusion: Using lingo in code should be avoided.

He elaborates a bit on what he means by "coding lingo" and a few general things to think about when naming your methods, variables, etc. His reminders include:

  • Going for clarity
  • Remembering that not everyone is English
  • That it can be excluding
  • It can be limiting

He reminds us that naming doesn't have to be "cool", it just needs to be useful and a developer-focused kind of documentation. He recommends using common names/terms for things, being concrete and avoiding abbreviation. There's a few other recommendations in the post too, so check out the full article for more.

tagged: coding lingo naming convention opinion recommendation

Link: https://medium.com/@frankdejonge/8ffae1a4fa4e

Paul Jones:
Some Rules For Good Naming
Apr 30, 2014 @ 09:29:42

Paul Jones has a new post to his site today talking about the importance of naming when it comes to the use of different patterns in development. He also makes some recommendations to help clear up some of the confusion around different names for the same things.

[Thoughts in a] Grumpy Programmer mailing-list essay got me thinking. [...] I completely agree with the emphasis on using a common vocabulary. One issue here is that naming things properly is very, very hard. It is one of the only two hard problems in programming. Are there any rules (even rules-of-thumb) that can we use to make it easier to pick good names for the classes and concepts in our projects?

He reminds readers that code is no place for a "novel context", that is that it's not meant to be instructions for humans, but instructions for computers. He points out that patterns are more about behavior than the name you give them and that picking a name that's "close enough" isn't a good idea. He also recommends that you avoid picking a name for a special context the code might be involved in.

tagged: naming rules opinion designpattern behavior context

Link: http://paul-m-jones.com/archives/5952

Paul Jones:
Quicker, Easier, More Seductive: Names, Usage, and Intent
Dec 18, 2013 @ 10:39:05

<p. Paul Jones has updated his "service locators vs dependency injection containers" series with another post to his site today, this time he focuses on implementation not names. He suggests that the difference in naming makes it easy to think they're very different things, so he focuses on implementation rather than just the names.

As the disucussion progressed, it became more clear to me that there really is no significant difference in how Dependency Injection containers and Service Locator containers are written. They are both Inversion of Control (IOC) containers, and are not distinguishable by their code, API, features, etc. (although some may have more or fewer features than others).

As such, the terms Dependency Injection and Service Locator appear to be interchangeable in the sense that a container is a container is a container. The difference in naming comes from how the container is used, not how the container is implemented.

He suggests that one of the main differences is where they are, either inside or outside of a non-Factory object. He circles back around to the names, though, and points out that when developers talk to one another, they need to be speaking the same language. As such, he tries to set this vocabulary for the implementations, separati

tagged: dependency injection service locator implementation naming

Link: http://paul-m-jones.com/archives/5853

Mathias Verraes:
Verbs in Class Names
Oct 07, 2013 @ 11:40:07

Mathias Verraes has an interesting post to his site suggesting that using verbs in class names can make for easier to understand and easier to read code - more "natural language."

When you first learned Object Oriented Programming, somebody probably told you that objects map to things. And that still holds true most of the time. And maybe somebody explained it using the simple heuristic to “look for the nouns”, which can indeed be a great discovery technique. But then somebody probably phrased that as “class names should not have verbs in them”. To me, that rule is severely limiting the possibilities for your models. So here are some cases where I prefer to use verbs.

He suggests that class names, in some cases, could be used as "messages" to the developers using them in the OOP. He includes some suggestions (based on the suggestion of nouns from another post) that use verb-names to convey what they're doing. He also talks about three specific cases - specifications, exceptions and interfaces - and includes samples of each using this idea of verb-based class names.

tagged: verb class naming noun alternative example

Link: http://verraes.net/2013/10/verbs-in-class-names/

Reddit.com:
Let's Make PHP's Function Names Consistent!
Jan 25, 2013 @ 10:32:57

On Reddit.com there's a heated discussion going on in response to this bug filed asking about aliasing PHP function names to make them more consistent (specifically "htmlentities_decode" versus "html_entity_decode").

[...] Current naming conventions are really horrible. For instance, look at differences between str_replace, strlen, parse_str, htmlspecialchars. All work with same type but their names are completely different. So, string functions should go to String namespace (Stringreplace()), array functions to Array namespace (Arraysearch()) and so on.

Back in the Reddit post most of the commentors agree that this kind of thing would be beneficial to the language, but - as several point out - this could have serious backwards compatibility issues. What do you think? Voice your opinion!

tagged: function naming consistency language opinion

Link: