Question

What are some of the best practices for clean code, naming conventions and documentation for PHP?

I see users/people saying this is a bad practice, Example:

// Create an array to hold x values
$arr_x = array();

That this is a unnecessary comment cause the syntax alone explains the functionality. That is should be more of a header comment that describes the script/function functionality rather than the variables/flow of the program. Example

/**
 * Create an array
 */
function create_array() {
   return array();
}

$arr_x = create_array();

// This is just to show the comments and the code is not tested or used except for this example

This has lead me down the path of proper syntax, coding and documentation (The reason for the title naming).

what is acceptable for variable, functions and script naming conventions or is this personal preference?

$varX
function varX()
varX.php

or

$var_x
function var_x()
var_x.php

I’m trying to find if there is a standard I should be conforming to. Thanks

Answer 1

There is no standard, just the opinions of developers.

I prefer to have variables delimited by underscores:

$my_var

But for functions I prefer camel-case:

function myFunction() {}

As for comments, yes sometimes comments such as // create array are not required at all, but don’t be put off using one liners, they won’t slow your script down when it is executed. I like to use one lines to neatly describe each step of a complex script.

As long as your code is readable for you and your fellow developers (others on a project, 3rd part companies etc) then you will be fine.