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

Freek Van der Herten:
Making overloaded functions readable
Jan 10, 2017 @ 12:18:19

Freek Van der Herten has a new post to his site sharing some of his ideas around making overloaded functions more readable, functions that can take in variable types of parameters (ex: both a string or an array) and can handle them correctly.

Sometimes you might allow a function to accept multiple data types. I don’t know for certain if it’s the correct term but for the remainder of this post I’m going to call such a function overloaded. In this post I’d like to show you a little trick to make overloaded functions more readable.

He starts off with an illustration from the Laravel framework of a "session" helper method that, in turn, calls "put" and checks for an array versus string input with some interesting logic behind it. He gives another example from a recent pull request where the code could be simplified using the same method as the "put" example, making it much more readable in the end. The post ends with one more example from this package and how the "respond" method was refactored with the same process, simplifying it down to a more readable and less-nested version.

tagged: overloaded method readability refactor loop variable argument

Link: https://murze.be/2017/01/making-overloaded-functions-readable/

Christian Mackeprang:
Writing good code: how to reduce the cognitive load of your code
Jun 22, 2016 @ 11:19:36

Christian Mackeprang has a post to his site with some ideas about reducing the "cognitive load" of your code - basically making it easier to follow, read and understand.

Low bug count, good performance, easy modification. Good code is high-impact, and is perhaps the main reason behind the existence of the proverbial 10x developer. And yet, despite it’s importance, it eludes new developers. Literature on the subject usually amounts to disconnected collections of tips. How can a new developer just memorize all that stuff? “Code Complete“, the greatest exponent in this matter, is 960 pages long!

I believe it’s possible to construct a simple mental framework that can be used with any language or library and which will lead to good quality code by default. There are five main concepts I will talk about here. Keep them in mind and writing good code should be a breeze.

His tips center around concepts like:

  • following coding standards for consistency
  • clarification through modularization
  • overall readability and application structure
  • good naming on variables and methods/functions

For each topic he gives a brief summary and some example code, usually showing what not to do and a solution or two to help with the clarification.

tagged: cognitive load understand readability consistency modularization

Link: http://chrismm.com/blog/how-to-reduce-the-cognitive-load-of-your-code/

Theo Kouzelis:
Improving Readability of PHPUnit Data Providers
Apr 10, 2015 @ 12:01:28

Theo Kouzelis has a recent tutorial posted showing you how to make your PHPUnit tests a bit cleaner with the help of data providers, a built-in tool for PHPUnit that allows for easier validation of larger datasets.

When writing tests I try to describe the test in the function name. I use the format testDoesSomethingWhenPassedSomething to first describe the assertion and then the context. [...] When I have many data sets running against the same test I will use the frameworks data providers to make the code less verbose.

He includes code examples to show both the difference between the single data tests and one using a set of email addresses to validate their correctness. He notes that the error message using data providers can be confusing (and maybe hide the real problem) so he offers a solution to make it more readable: associative arrays. The trick is that PHPUnit uses the key to display the error and by making this unique you can make the error output more informative.

tagged: dataprovider tutorial readability phpunit unittest associative array

Link: http://theo.codes/php/improving-readability-of-phpunit-data-providers.html

Vinícius Krolow:
Some tips to improve your codes readability
Jan 25, 2013 @ 09:53:55

In this new post to his site Vinícius Krolow shares some tips he thinks will help to make your PHP code more readable in the long run.

What about code readability, from my point of view is one of the most important thing in the code. Who writes code that is easy to read, writes good code. Probably reading code is where you spent most part of your time, and not only your code, probably code of your team mates, or maybe code from the open source community, so write code that is simple and is easy to understand it’s really important.

His tips (seven of them) are:

  • Comment before write your code (DocBlock)
  • Return frequently, Return early
  • Break, Continue
  • Code Standard / Name conventions
  • Throw Exception
  • Comment often, but not write stupid comments
  • Methods can be always smaller than they are

It's a little difficult to read as the English isn't the speaker's native tongue, but it gets the point across. He also recommends reading this if you'd like more information about writing better OOP code that's easier to read.

tagged: code readability recommendations structure comments conventions


Practical Code Refactoring, Part 2 - Readability
Oct 22, 2012 @ 10:16:03

PHPMaster.com has returned with the second part of their guide to code refactoring. In this second part they pick up where they left off and focus on code readability this time.

In part one of this series I introduced what constitutes good code. As the series on code refactoring continues we’ll dive into each of the three aspects and see how to refactor for each of them in order: readability, extensibility, and efficiency. In this part, the focus is on refactoring your code for better readability. Recall the definition of readability: readable code follows some well-known style and documentation practices. To help you start refactoring your code for readability, I’ve prepared this list of questions you should ask yourself throughout the development, testing, and review process.

There's a few different types of things that contribute to readable code, so he breaks the article up into a few sections:

  • General things like coding style guides, header comments and a reduction of global code
  • Naming conventions, well-named variables and methods
  • Simplified and easy to use expressions
  • Blocks of code, their average size and complexity.
tagged: readability code refactor guide tutorial series


Volker Dusch's Blog:
Mandatory "Template Engines (Twig) vs Plain Old PHP" Post
Mar 22, 2011 @ 09:44:37

Volker Dusch has posted what he calls his mandatory templating post comparing the benefits of using plain PHP for templates versus the Twig.

If you read some of my previous posts you know me as a "clean code" guy. I like readable, understandable and maintainable code. The same goes for templates. I need to be able to parse very quickly what is happening.. at least i want to.

He argues that, because the syntax of something like Twig is so much simpler and more readable, it's a better solution in the long run (technical considerations not withstanding). As an example he provides a side by side comparison visual image of the a template for each.

tagged: twig template readability compare


Matthew Weier O'Phinney's Blog:
Why PHP Namespaces Matter
Feb 04, 2011 @ 13:23:22

Matthew Weier O'Phinney has a new post today talking about why namespaces in PHP matter and why he thinks they're a valuable contribution to the language.

You've heard about PHP namespaces by now. Most likely, you've heard about -- and likely participated in -- the bikeshedding surrounding the selection of the namespace separator. Regardless of your thoughts on the namespace separator, or how namespaces may or may not work in other languages, I submit to you several reasons for why I think namespaces in PHP are a positive addition to the language.

He breaks down his reasons into four different categories - the code organization benefits that come with namespace "containers", simplified interface structure, improved readability (no more huge class names) and a simpler method for identifying dependencies

tagged: namespace opinion organization interface readability dependencies


Brandon Savage's Blog:
Stop Sacrificing Readability For Efficiency!
Mar 27, 2009 @ 12:58:28

Brandon Savage has a recommendation fro developers out there - sometimes readability is more important than any micro-efficiency you might gain in your scripts.

Much was made last week over the topic of micro optimization in PHP. Most of these argued that micro optimization was a bad idea. [...] There’s another reason that micro optimization can be a bad choice: it makes code absolutely impossible to read!

He points out one example for validating the length of a string in two ways - one using isset to tell which characters in a string are set and the other using the tride and true call to strlen. The first, while benchmarked to give you a (very tiny) improvements, is harder to read at first glance than the check to the string length.

tagged: readability efficiency performance microoptimizations benchmark


Shawn Stratton's Blog:
Code Readability, Part 1
Jan 13, 2009 @ 10:20:28

Shawn Stratton has posted the first part of his series looking at "Code Readability". This part focuses on something that is often woefully forgotten by many developers - proper code commenting.

The simplicity of PHP can sometimes be overwhelming, with so many different ways and approaches to creating solutions for our problems we sometimes lose the ability to think past the current problem and into the future. [...] Today I'm going to try to address some quick ideas that most of you will already be familiar with, things that will aide in the general readability of code for future generations.

He looks at the difference between useful and non-useful comments: DocBlocks, putting them near decisions, listing array parameters, recording TODOs and how it can all help you generate API documentation quickly and easily.

tagged: readability docblock comment useful series


SitePoint PHP Blog:
Which reference sites do you trust?
Aug 30, 2007 @ 10:43:00

The SitePoint PHP blog has a post that asks developers "Which reference sites do you trust?"

While completing the tech edit on the 2nd edition of the PHP Anthology the issue of linking came up; specifically, linking to authoritative reference material on the web. [...] The issue isn't simple one. Regarding PHP, the php.net manual is the authoritative reference site. The various web technology standards are also represented by authority web sites.

So what does he thing makes for a good, trustworthy resource? He includes criteria divided up into three sections - readability, accuracy & trustworthiness and longevity.

tagged: reference website manual readability accuracy trustworthiness longevity reference website manual readability accuracy trustworthiness longevity