Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
147 lines (97 sloc) 6.82 KB

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” – Martin Fowler, Refactoring: Improving the Design of Existing Code.

Code style

It's common for development teams to have a coding style guide— a set of rules for how code should be written, which covers details like:

  • Case conventions - e.g., when/where to use lowerCamelCase, snake_case, UpperCamelCase, etc.
  • Structural conventions - e.g., whether to use spaces or tabs, where to place braces, what's the maximum length a line of code should be, etc.
  • Etc...

The purpose of a style guide is to keep work consistent amongst a group of developers. Even if you're working independently, abiding by a style guide will help produce more consistent code that's less prone to errors.

As an example, this is the Ruby style guide that the team at Github.com uses.

On a more macro level, sometimes entire languages have dedicated style guides, such as the case with Python's PEP 8 style guide.

PHP has two style guides maintained by the PHP Framework Interop Group (FIG):

When a language has an official style guide, it's not required that it be implemented 100%, and teams may decide to go off course with their own variations. The emphasis on style is not about which style guide you're following, simply that you are following some style guide and are aiming to be consistent and thoughtful in regards to code design.

In this course, we will follow the PSR-1/PSR-2 guidelines in our PHP code files

You can diverge from these guidelines, but you will be required to outline your divergences in your project's README.md file, and the divergences must be reasonable.

PhpStorm will mostly keep you in line with the guidelines, so use it to reformat your code often, and pay attention to warnings/notes it shows you.

Example

Consider the following code example which is problematic in several ways:

<?php

function getCelsius($temperature = NULL,$includeUnit = TRUE) {

    # $x = ($temprature * 1.8 + 32 # f -> c
    $x = ($temprature - 32) / 1.8

    if ($includeUnit == TRUE) {

        return $x .= ' C';
    }
    else{
        return $x;


    }
}

?>

Things PhpStorm will clean-up for you when you Reformat Code:

  • Constants, booleans, and null values should be lowercase.
  • Comma separated lists (e.g. the parameter list) should have a space after each comma.
  • Inconsistent spacing of braces after the if and else.
  • Function/method opening brace should be on its own line.
  • Unnecessary closing PHP tag.
  • Extra spacing between lines.
  • Incorrect indentation— the first return statement is a child of the if construct and thus it should be indented.

Things PhpStorm will alert you about:

  • There's a typo in the variable name ($temprature should be $temperature).
  • Missing semi-colon at the end of the line setting variable $x.
  • Unnecessary closing PHP tag

General problems that PhpStorm can't catch but you should be aware of:

  • The variable name $x is generic and in a larger context it could be confusing. A better name would be $result.
  • There's a commented-out line of code that's not being used, and no context is provided as to why it's still there. Lines like this should be cleaned up when finalizing a project. Exceptions are made if you comment that you're leaving the old code in for learning purposes.
  • The structure/use of the if/else construct and return statement could be optimized.

Here's that same example, cleaned up and optimized:

<?php

function getCelsius($temperature = null, $includeUnit = true)
{
    $result = ($temperature - 32) / 1.8;

    if ($includeUnit) {
        $result .= ' C';
    }

    return $result;
}

Comments

"Good comments don't repeat the code or explain it. They clarify its intent. Comments should explain, at a higher level of abstraction than the code, what you're trying to do." -Steve McConnell

The PSR guidelines offer no rules on PHP commenting style, so any of the following PHP commenting styles are acceptable.

Multi-line block comment:

/* 
This is a 
multi-line
comment in PHP
*/

Single line inline comments:

# This is a single line in comment using a hash sign

// This is also a single line comment using two forward slashes, or "C++ style"

Other, non-PHP code

There are no specific style guides I ask you adhere to when it comes to JavaScript, CSS, or HTML in your work.

However, just like PHP, it's expected that this code is consistent and neat for maximum legibility, following the best practices and requirements for the respective language.

That being said, here are some common issues I see in student's HTML code that you should avoid:

Validating HTML

During development and before submission, run any/all pages of your project via the w3 validator to identify and fix any errors or warnings. (If you disagree with any of the warnings the validator is showing, email me ahead of time so we can confer on whether ignoring the warning is acceptable).

PHP Code in display files

You may diverge PSR-1/PSR-2 guidelines in display files (.html, .blade.php) that incorporate PHP if it's for the purposes of writing more legible display code.