PHP, HTML, Javascript and writing good practices

softwareengineering.stackexchange https://softwareengineering.stackexchange.com/questions/9584

Pergunta

I realized I have to write down a convention specification about HTML, JavaScript and PHP coding for me and my team.

In web development, just like in C++, I'm definitely a fan of indentation and comments.

Nonetheless, often in my work I encounter HTML+JavaScript+PHP code which suddenly brings up the headache.

I'm trying to make my code readable, but what seems to be better to me (to indent & comment) seems not to fascinate my teammates, so I was wondering if there is a best or at least shared good practice when writing "hybrid" documents just like today's web pages, which day by day become more and more complex.

I'm aware of the fact that probably it is in the nature of today's web pages' code to be a little bit intricated, but I wonder if a good convention concerning these aspects already exists.

Foi útil?

Solução

Some general rules I follow:

General

  • Indents are 4 spaces.
  • Indent new levels
  • Comments are < ~80 chars from the indent level. If I'm in two levels (8 spaces) that means the cursor stop will be around 88 characters.
  • Use multi-line comments. I prefer the look, however this is a subjective point.
  • Comment now rather then later when you have no idea what's going on.
  • Allman style braces. It's cleaner and is more readable. Subjective.

JavaScript

  • Use a library. jQuery in particular is very good. It eliminates all cross browser headaches.
  • Understand that ID's are for particular elements, classes are for styles. ID's shouldn't be used more then once per page and they will have particular hooks attached to them. Use classes for things like navigation.
  • Out source into methods. It's tempting to put all the code into the bind call, however putting it in it's own function will increase the flexibility of your code.
  • Use functions instead of evals. That means setTimeout(function(){ /* Do something */ }, 1000); instead of setTimeout('doSomething', 1000);
  • Use local variables with var.

HTML

  • Semantic markup. Use appropriate tags. Don't put <br />'s in there to add space, adjust margins and CSS rules.
  • All tags are lowercase.
  • All tags should end with a closing tag or be self closing.
  • Make use of classes for layout that is similar. Have a couple of predefined classes like hide, clear, error, etc.
  • Everything (scripts included) should go in <head>. Worry about optimizing (moving stuff around) when it presents a problem.
  • External stylesheets and JavaScript source is a must unless it is page specific.

PHP

  • Frameworks are good, I recommend CodeIgniter.
  • If you don't want to use a framework, try to use the latest version of PHP possible. (That means 5.3).
  • Use includes to your advantage.
  • Clear injections or use prepared statements.

  • Perform if checks on preconceived fail-secure values.

    $logged_in = false;
if(check_user($user))
{
     $logged_in = true;
     $user = load_user($_SESSION);
}
  • Know the difference between single and double quotes. Use single quotes when possible.
  • Don't echo HTML.

Outras dicas

Keep the 3 separate. The least maintainable code I deal with is always when there is some PHP that's echoing out a lot of HTML & JavaScript, probably with some SQL thrown around for good measure.

Keeping all of them as separate will make the code a lot easier to maintain, and also makes things a lot more streamlined if you have people working on different parts of the application, such as designer who only needs to work with the HTML/CSS.

There are some reading for inspiration :

  • Zend Framework - php coding style : List of practices how to write maintable php code (PHP File Formatting, Naming Conventions, Coding Style: Arrays, String, Class, Method eg.).
  • Google - code style guide : List of practices how to write maintable javascript code (Rules: Constans, Semicolons, Nested Function ..., Coding style: Naming, Scope, String, Visibility fields etc.).

The easiest way to code a php web app is certainly to mash everything together. You quickly wind up with an unmaintainable mess if you do things that way, however.

Here are some good practices:

1) Put your JavaScript in the <head> of a document (or, better yet, in separate files that are referenced in the head). Learn how to bind event listeners in an document.onload event, rather than scattering them through your html. (Better yet, learn to use a framework like Jquery; it'll make your JavaScript much, much prettier).

2) Look up design patterns like MVC. You want to separate your business logic, written in PHP, from your HTML as much as possible. Ideally, you end up using a nice templating language to put together your HTML pages; at the very least, the PHP in your HTML should be terse -- mainly calling variables and looping through lists that are built elsewhere.

3) Comments, indenting ... that stuff is just basic programming best practices. I tend to let my line length go above 80 characters when I'm writing HTML, just because the language is so damn verbose, but that's about the only traditional practice you should let slide -- if the rest of the team is being sloppy, they need to suck it up and shape up.

Here's a couple of tidbits:

Javascript: Use var when initialising variables.

HTML: Include scripts at the bottom of the file so they load last.

PHP: Split the files up. Don't put all your classes in one file, just as you wouldn't in normal C++ development. Comment as much as possible and also write down the purpose of your functions/classes.

Licenciado em: CC-BY-SA com atribuição
scroll top