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.

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.

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.

would you mind explaining more on what these resources do and why do you recommend these as answering the question asked? "Link-only answers" are not quite welcome at Stack Exchange
–
gnatJun 7 '13 at 6:10

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.