User:Pegeraki/HB Standards

WolfTech Webteam Handbook

• Introduction
  • The Three Rules
  • Organizational Structure
  • Wolftech Webteam Epilogue
  • Getting Paid
    • Employment Forms
    • W-2 Forms
    • Payday Tool
    • Timesheet Schedule
    • Late Timesheets
  • Tools of the Trade
    • Your Computer
    • Your Accounts
    • Mailing Lists
• Work Environment
  • Dress Code
  • Training
  • Getting Help
  • Getting Projects
    • From Projex
    • From Remedy
  • Working in AFS
    • Beta Folder
    • ECE Template
• Coding and Scripting
  • PHP
  • MySQL
  • Shell Scripts
  • Cron Jobs
  • Debugging
  • Standards

Coding Standards

Writing good code is a combination of experience and structure. Clearly, the more experience you have coding, the easier it will be for you to see the big picture of your code and write with that in mind. However, when you are just begining to program, this can be difficult, espescially if you do not have a plan in mind from the beginning. Thus, it is helpful to sit down and lay out a plan for how you want the code to look before you even begin coding. This will give your code a general logic from which everything stems. Without following such a plan, your code will likely end up as spaghetti code.

Some implications of bad coding include:

• Poor readability. When your code doesn't work, you show it to someone else for help. But, you all spend so much time figuring out what each section of the code is supposed to do, that you are unable to actually analyze the code for errors. Your code is written in such a way that nobody else can read it. This means you are SOL when trying to get any sort of help.
• Minor edits break code. Sure, your code works fine now, but what happens when you have to add a feature, or change some detail? Well, in this case, one of three things will happen.
  • The best case is that you look at your code, are baffled by what you did and rewrite the code in a sensible manner. This prevents others from seeing your little blunder, and it ensures that your code will have a longer lifetime.
  • Another situation is that you go back and edit your code, without making any significant changes, but adding in the feature you were trying to add. This only perpetuates your sloppy code.
  • What is most likely to happen is that someone else will have to edit your code. They will have to spend a lot of time and effort figuring out what is going on with your code. After they thing they have things figured out, they then begin editing your code, hoping and praying that it doesn't break. The absolute worst thing that could happen here is that somebody else has to go back and completely rewrite the code which you so sloppily designed the first time.
• Having to rewrite code. This will happen if you tangle a bunch of code togther is a haphazardly manner. If you begin writing large blocks of code without any central planning, you can easily get screwed and have to begin the entire project over. This translates into a gigantic waste of time and effort.

Now, you don't have to be a brain surgeon to write decent looking code (why would a brain surgeon write code anyway?). The purpose of this document is to present some general guidelines to use for creating most of your PHP scripts. By all means, these are not laws, but certainly something to keep in mind while coding. Do not regard this as an attack on your style, but rather incorporate it into your own coding style.

What is by far the most important concept to keep in mind while writing PHP code, or for that matter any web-based code, is to separate the code from the content. By separating the code from the content, you place as much of the PHP, MySQL, and other queries at the top of the page as possible and then follow it with whatever HTML output you desire. A sample of what this might look like is considered below. In addition, comment your code so that you and others know what is going on inside the code. Adding a concise, informative blurb at the beginning of each code block can make a world of difference.

As the example shows, there is no PHP code in the lower half of the page. However, this is not very realistic for actual web pages. You will pretty much always have some variable to look up, table entry to query, etc which will prevent you from completely separating your code. The idea, though, is that we get as much of the PHP out of the way at the begining of the file, and only make minor calls later on. In the HTML part you should only need to output statements (echo/print) and control statements (if/for/while etc). Use of echo statements to output the main HTML should be avoided at all times. Also, NO SQL statements should appear in the lower part of the script. Also notice that the comments are kept to a minimum and tell us exactly what the next small chunk of code will do.

<?php
// Initialization of variables (database etc)

// Take care of form submission
if (isset($_POST['submit'])) {
// Check form variables for errors
...

// Do something with the form data
...
}

// Any other processing before we display the page
...

// ----------------- START HTML OUTPUT ------------------
?>
<html>
<head>
<title>Cool page</title>
</head>
<body>


Cool content




</body>
</html>