twhite96
8/31/2016 - 2:47 AM

Style guide for writing code in cs0134 and cs1520

Style guide for writing code in cs0134 and cs1520

styleGuide.md
content_copyfile_download
  • Rendered
  • Source

Introduction

This is the style guide that you will be required to follow for any and all code submissions in this class. There is a very good chance that, should you decide to venture out into the wild and develop software professionally, you will be required to follow some sort of coding standard. All submissions must adhere to this style guide, if they don't there will be penalties up to and including the submission not being accepted or cosidered for a grade. You're in luck though, as this is a relatively easy style guide to follow. Suggestions are always welcome and above all else, even if you hate style guides and vow solemnly never to follow one again in your whole life...just make sure your code is consistent. Your future self will thank you. On a side note, it will be relatively apparent to me if you don't follow the style guide.

If changes are made to this guide throughout the semester, I will be sure to let you know and discuss the change with you.

General

Indentation

2 spaces. Not tabs. Not 3 spaces. Not 4 spaces in one section and 2 tabs in another. 2 spaces for the entire project. You can tell just about any text editor to make your default indentation 2 spaces. I can help you find out hwo to do this, or it will be a quick google search away.

Whitespace

Whitespace refers to an extra space (or spaces) at the end of a line or anywhere else in general, to be honest. For our purposes though, make sure not to leave any trailing white space at the end of your lines and make sure there is a single new line at the end of the file.

HTML

NOTE: You may see html written a certain way in your textbook that deviates from what you see here. Don't pay any attention to that.

Example 1:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <link href="/css/styles.css" rel="stylesheet">
  </head>
  
  <body>
    <header></header>
    
    <footer></footer>
    
    <script>
      // some cool scripts here
    </script>
  </body>
</html>

Notice the following:

  • we will only be using html5, no other version is acceptable
  • character encoding should be UTF-8
  • tag names are always lower case
  • omit the type attribute from script tags and link tags
  • always use semantic html (the right tag for the righ job)

Example 2:

<div class="class-name" id="someId">
  <p class="text">Awesome Text!</p>
  
  <ul>
    <li>List item 1</li>
    <li>List item 2</li>
    <li>List item 3</li>
  </ul>
</div>

Notice the following:

  • class names are hyphenated
  • id names are camel cased
  • both classes and ids should have meaningful, identifiable names
  • new line after block, list, or table element
  • double quotes for attribute values

CSS

NOTE: You may see html written a certain way in your textbook that deviates from what you see here. Don't pay any attention to that.

Example 1:

.meaningful-classname {
  color: #000;
  margin: 10px 0;
}

#uniqueId {
  background: url('/images/bg.png') no-repeat right center;
}

Notice the following:

  • ids and class names should be as short as possible, but as long as necessary
  • no unit for zero values
  • use a 3 character hex value when possible
  • use shorthand when possible
  • indent all block content
  • space after property colon
  • separate rules with new lines
  • group sections with a comment
  • use single quotes

Javascript

The good folks over at airbnb have released a comprehensive, easy to use javascript style guide. Rather than dumping it into this gist, I will just link to it instead. They have specs for all aspects of js, but we will just be concentrating on es5 (or the previous version of JS, still commonly used, but favored less to to es6) Don't hesitate to ask if you have any questions about this styleguide. You can find it here

PHP

Example 1:

$variable = array();
$boolVal = FALSE;

public function coolFunction() {
  // code goes here
}

if ($boolVal === FALSE) {
  // other code here
}

foreach ($variable as $v) {
  // something will happen more than once
}

Notice the following:

  • space after if and foreach keywords
  • curly brace on same line as function declaration
  • camel case variables
  • semicolons at the end of the line

Example 2:

<?php foreach ($something as $s) { ?>
  <li>$s['key'];</li>
<?php } ?>

<?php if ($condition) { ?>
  // do something
<?php } else { ?>
  // do something else
<? } ?>

Notice the following:

  • loops and conditionals should be written as above when interleaving in html
  • always close your php blocks
  • be concise and write your code as cleanly as possible