General Coding Guidelines

CONTRIBUTING.md

Summary

This document serves as a guide to contributing in the admin project.

SQL

Since we have used MySQL for our database component. A scheme for naming things in MySQL has been developed, we follow this general guidelines:

• Table names should be words in their noun form.
• Table names should be pluralized.
• Table names containing multiple words should be separated with the underscore character _.
• Every table should contain an id column, which serves as the Surrogate key.
• Pivot tables should be named as follows: the first table name is determined alphabetically, it should be appended with an underscore and the pluralized second table's name. Ex. pivot table for students and courses: course_students.
• Attribute names containing multiple words should be separated with the underscore character _. Attribute names maybe in their pluralized or singular form use anything that is appropriate.

Code formatting guidelines

Since our php code base mainly uses a procedural style approach, we will stick to that. We follow a modified K&R formatting guideline, In summary follow these:

• Use 4 spaces instead of the tab character for indention.
• We should generaly use single quotes. Prefer ' than " in your php code, use " only when necessary. HTML code uses double quotes.
• Any content inside a { structure should be indented.
• functions should be formatted like this:

function foo($arg1, $arg2)
{
    return what_ever();
}

• if-else Conditionals should look like this:

if ($foo > $bar) {
    print_r($bar);
} else if ($fooo) {
    foo_bar();
} else {
    bar_foo();
}

• Don't indent after <?php ex:

<?php
$hello

• require/s and include/s should NOT be surrounded with parenthesis (() chars:

require '../includes/header.php';

• When outputting HTML code it is recommended to escape in and out of php.

<?php
/* Some Code */
?>
<pre>Hello World</pre>

• (important) HTML code formatting please follow this: google-styleguides.

• From google-styleguides:

  Be consistent.

  If you’re editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too.

  The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you’re saying rather than on how you’re saying it. We present global style rules here so people know the vocabulary, but local style is also important. If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Avoid this.

Standard Directory Structure

Modules are folders in the root directory excluding includes. Each module should contain files as pertained in the illustration below. (important) also note that although it is a guideline to include all of this files in a module you are encouraged to add more files for code modularity ex. table.php a program for producing a table, or table_with_controls.php a program that generates an HTML table with controls.

/
└── (module)
    ├── create.php
    ├── read.php
    ├── update.php
    ├── delete.php
    └── index.php

The index.php

This program should show all the records created in the module with associated controls to those records (update, delete, read). Additionally a create control should be accessible in this program. This template should be followed, generally:

<?php

require '../includes/dbcon.php';
include '../includes/header.php';

?>

<a href="create.php">Create new $module</a>
<?php $items = array(1, 2, 3); // Replace code to read from DB ?>
<table>
<?php foreach ($items as $item) { ?>
    <tr>
        <td><a href="read.php?id=<?= $item ?>"><?= $item ?></a></td>
        <td><a href="update.php?id=<?= $item ?>">Edit</a></td>
        <td><a href="delete.php?id=<?= $item ?>">Delete</a></td>
    </tr>
<?php } ?>
</table>

<?php

include '../includes/footer.php';

The create.php

This program shows a form which enables the creation of a record related to the module. This template should be followed:

<?php

include '../includes/dbcon.php';

function has_required_params()
{
	return isset($_POST['foo']) && isset($_POST['bar']);
}

if (has_required_params()) {
	// Do some DB work here
	header('Location: index.php'); // Redirection
}

// show the form if has_required_params() fails
include '../includes/header.php';

?>

<form action="create.php" method="post">
	<input type="date" name="foo">
	<input type="number" name="bar">
	<input type="submit">
</form>

<?php

include '../includes/footer.php';

The read.php

This function reads an object from the database and renders it in a browser readable format (HTML).

<?php

include '../includes/dbcon.php';

function has_required_params()
{
	return isset($_GET['id']);
}

if (has_required_params()) {
    // get model obj from db
}

include '../includes/header.php';

?>

<!-- Show the data about the record here -->
<!-- Also show necessary error messages here -->

<?php

include '../includes/footer.php';

The update.php

Show a form that updates an already existing record, processing this input should be done through this form.

<?php

include '../includes/dbcon.php';

function has_required_params()
{
    return isset($_GET['id']);
}

function has_required_post_params()
{
    return isset($_POST['foo']) && isset($_POST['bar']);
}

if (has_required_post_params()) {
    // update database model
    header('Location: index.php'); // Redirect to index
}

if (has_required_params()) {
    // read model obj from db
} else {
    header('Location: index.php'); // Redirect to index
}

include '../includes/header.php';

?>

<!-- Also Show necessary error messages -->
<form action="update.php?id=<?= $item->id ?>" method="post">
	<input type="date" name="foo">
	<input type="number" name="bar">
	<input type="submit">
</form>

<?php

include '../includes/footer.php';

The delete.php

Delete a record from the database, showing a form here is unnecessary.

<?php

include '../includes/dbcon.php';

function has_required_params()
{
	return isset($_GET['id']);
}

if (has_required_params()) {
    // delete model obj from db
    header('Location: index.php'); // Redirect to index after the delete
} else {
    // show error using sessions
}