HirdWeb » Ideas and Sorts

Code Standards

stephen — Wed, 28 Jul 2010 16:05:05 +0000

As I have been going through different code bases, I keep seeing things that just really amaze me. It all surrounds coding standards, or the lack thereof. Different places have different ideas of what is best, and I can only offer mine to the fray. However, once a standard is in place, no matter how odd it may be, it is important to keep to those standards. This is for a few reasons.

First, it is important for readability. By seeing the code in the same format and structure it helps to get through lines of code quickly. It helps because all of the code is in the same format throughout the code. The person looking at the code can quickly understand without having to go back and figure out what is happening because the code is all of a sudden out of whack and what you may think is happening may not be happening. Especially when indentation may also be out of line and brackets are not used. Take for example the two examples below

$fin=0;
foreach($var as $v){
if($v==3){$fin=$v+3}
unset($fin);echo $v;
}

As a stand alone example it may be easy to decipher what is happening. In a file that has over 3000 lines of code, it may be overlooked and even cause issues if changes are made that affect that block. By breaking from the set coding standards and doing it “your own way”, sure it may be quicker for you, but it creates havoc, even for you later on.

Second, it is about cleanliness. Using the same block of code above, that looks absolutely horrid to me. I know some people code this way because “it takes up less space”, some even make a claim that it makes the code process faster. To that point, if you need to cut down on whitespace in the code in order to get the application to go faster, then maybe you ought to look at the code again, because it is likely something else that is causing problems, not the whitespace. If that code block again had been done with a few standards in place, it could look like this instead:

$fin = 0;
foreach ( $var as $v ) {
    if ( $v == 3 ) {
        $fin = $v + 3;
    }

    unset($fin);
    echo $v;
}

By doing this, the code looks cleaner, which adds to its readability. Clean code not only looks good, but is very easy to do. It helps to maintain the flow of work, especially in larger projects. By sticking to a clean code standard, all developers can jump in at any time and pick up easily, as everything is nicely placed, and easy to understand. There will be times when you write some code, then do not touch it for months, maybe years, and have to go back to review something. You will be very glad if you kept to standards and kept your code clean.

Third, it is about working in the team. If you are alone in the project, then great. You get to choose how you want to work. Most times it is more than just you, so it is important that everyone works in the same standards. This can be up to the team to determine. This can include spacing, indentation, bracket use, variable naming conventions, ternary use, etc. But whatever the team decides, stick to it. Do not be a rogue and do it your own way just because you think it is better. Having the code in a standardized format really, really helps in the long run. Teams are able to debug code quicker because they do not have to decipher different standards. Coding can happen in a dynamic environment where you may be working on a data object one day, then have to switch to help with the controller layer the next. You will not have to go through the code and decipher the different styles.

With that being said, some of the standards that I use may not work for everyone. I am a little neurotic and OCD when it comes to code, so I like a specific style, but can adapt as needed. Here are some of the things I use:

Variables names must be descriptive of what they represent, the only exception being is for counters/iterators
for example, a variable for total amount would be $total, or the variable for tax would be $tax, or the variable for a unique identifier would be $uid.
For loops, If and Switch statements must be bracketed, must have spaces between the parenthesis, and must be indented. The length of indentation I usually use 4 spaces (or set the tab stops to 4 spaces). Switch statements must have indentations for each case. Example:
```
if ( $var = 0 ) {
    // do something
}

for ( $c = 0; $c <=5; $c++ ) {
    // do something
}

switch ( $var ) {
    case 1:
        // do something
        break;
    case 2:
        // do something
        break;
    default:
        // do something
} 
```
There should never be any If statement or loop that is never bracketed, ever. I think that is lazy coding, I think it looks atrocious, and when more code is needing to be added to the struct, it causes more time wasted to ensure that the proper items are included.
Functions should be bracketed, and indented, even if it is only one line of code in the function. Comments should also be done on every function describing the purpose of the function.
Comments describing functions/objects/classes should follow the same format. If PHPDoc is used, then use it throughout. Do not change the way you comment these. I have seen functions in a file commented using PHPDoc, using the "// ----- description", and then surrounded by "//" around the entire comments. I really do not care which one to use, but when one is decided to be used, use only that.
Never, ever use short tags, or short echo tags. They are just bad form, another example of lazy coding, and will cause problems here soon. Even though PHP6 is all but dead, the "enhancement" to remove short tag/short echo tag will make it to a release here soon. I understand the old PHP4 was all over it, but should not have been. Use the full tag and do not use "Do not just copy and paste code to other parts of the application. If you find that a code block can be re-used in other areas, then wrap it in a function, or an object/class, and keep the code centralized. When the code needs to be updated, you then only have to update one section, instead of multiple files.

OK, so my rant is over. The list above is my standards. This may not always work in every project. Some of the good areas to look at for ideas or practices for code standards are:
http://pear.php.net/manual/en/standards.php
http://framework.zend.com/manual/en/coding-standard.html
https://trac.cakephp.org/wiki/Developement/CodingStandards

Most of the standards I use are located in these documents.

Apple iPhone Development

stephen — Thu, 16 Apr 2009 14:20:00 +0000

Just a quick post here. Not a lot of time to do anything really earth shattering in this post. I have recently purchased a book to help me start to code some apps for the iPhone and iPod Touch. I am starting out slow, then going to work my way up to some really cool apps. I think one of the things I will create first is an app that can download site content for use offline. I am sure there are a ton of apps out there that do that, ie like readers, feeds etc, but i was looking to start with something that would help me, and then grow from there.

Here is the book I bought:
iPhone Development
by Dave Mark and Jeff LaMarche
Apress

Not sure when I will have time to get through this. But I will. Also, if there are any other books, or better resources to look at, please let me know. There are a few apps I have in mind for all portable/phone devices I want to do, but as with the rest of the world, money is a little tight right now and have to start somewhere.

Quick note about change

stephen — Mon, 13 Apr 2009 00:49:20 +0000

Just a quick note about the change. Needed a change to the site. So I downloaded a good theme, and changed a couple things about it. More of a minimalist approach, not as gimmicky as the old theme, and is a whole lot more “neutral” in color.

Hopefully it will stick around for a while.

Ideas to help code

stephen — Tue, 31 Mar 2009 15:47:14 +0000

I have caught myself doing this often, and need to always regroup and figure out what is a better way to do these types of things. I am speaking of coding in absolutes. What does this mean? Coding a type of block that is hard set to do something exactly. Like for an example, let’s say that there is a calendar application. In this calendar application, there are four languages to select from, so a code block does something like this:

// Controller file
$eng = $this->Users->Select("language", "English");
$spn = $this->Users->Select("language", "Spanish");
$gmn = $this->Users->Select("language", "German");
$fre = $this->Users->Select("language", "French");

**Note this is not using any kind of construct in CakePHP, Symfony or any particular framework, just an example of a User class with a function called Select passing in 2 variables.

As an example, the view of this same code may be something like:

// Controller File
$this->set('lang', array($eng, $spn, $gmn, $fre);

Now while this may work for the time being, it could cause a hassle later on if there are more languages that the application will need to support.

Now, this is not saying that the above example is bad practice, because it is entirely possible that it will only need these two languages. Like if you were programming an application for a Canadian business, it would need to have both English and French. There may never be a requirement for Spanish, German, or any other language. What I am doing more of now, is making things more dynamic, to handle new items seamlessly and with little new code.

Taking the above example, we could put it into something like so:

// Model File
class User extends someBaseModelObject {
. . .
function getLanguages(){
      $langs = array(
          "English", "German", "Spanish", "French"
      );
      return $langs;
}

// Controller File
$langs = $this->User->getLanguages();

$this->set('lang', $langs);

Now if there is a new language, all that needs to be updated is the Model file instead of adding new lines of code to one part, updating another line of code in another part, and so on.

Is this possibly an oversimplification of this idea? Yes it is. But I do not write this as a simplification, but to just show something I am starting to focus on more, is that I need to make things more dynamic so I do not have to re-do code as new things are added. I use language as an example in this post, because that is just an easy example to show. There are many things that could be done for dynamic purposes. It is all about thinking about the right way to code.

Non Code Code

stephen — Wed, 18 Feb 2009 01:17:33 +0000

We all get to a point in the coding process where there needs to be “non-code” code. This does not have the same type of structure or verbiage as the construct of PHP, C# or anything else. This is our own little distinct code.

It may seem like I am talking about lol-catz, which I am not. This is the code we do inside of our code. It extends beyond the logic of the code, or hopefully it does. If your own little code defies all logic, then maybe the code will break hard one day. This code is our own little way of saying how we are putting the code together. This is the notes/documentation that we write (or fail to write), the variable naming convention, object/function naming, any user messages we write, and error trapping/error handling we do. And there is more, this is just a few of the things that we get to write our own “code”.

One of the funniest things for me to do is to go back and look at some of my very first code. I look at the documentation I did, and it is funny to read. Some of the things I actually am scratching my head wondering what I was meaning half the time. The variables have great names which only partially tell what they were supposed to be doing. And the best is looking at the old VB 6 code where the variables followed the Microsoft horrendous naming structure.

Why do I write this and not about real code? Because there will be a time that you will be on both sides, writing and reading, and before you get upset that the person previous to you did not know what they were doing, they probably did. They wrote their non-code code perfectly for them and may have even understood their words at one time. And as sure as that will happen, you will write something that someone else will come in and scratch their head and say “What?”

So take it all in stride. Laugh about it, decipher it, and go forward. There is not enough time in the day to sit and stew about bad code/bad documentation/bad variable naming/bad non-code code.

And next post, I really do promise I will write more about actual code.

Things on my mind

stephen — Tue, 13 Jan 2009 10:14:56 +0000

OK, so I am a little late in posting something for the New Year. Now that college football season is over, there is less distractions for me on the TV. In my last post, I mentioned that my only New Year’s resolution was to take down the Christmas Tree. Well, I have done that, so this year is a success.

Now for some of the code stuff going on, more applications appear to be on the horizon. Some are big for a project, others are a couple of things that should be able to be completed fairly quickly. Some will have newer, “flashy” things on them, more integrated AJAX and what not.

But the real excitement is the new MacBook Pro 17″. I was hoping they would do that one soon, and now that they have, I think I want to get it. I just need to convince my wife that it is the right investment to do. Maybe I need to take on a few different projects here and there to help me out to get that new MBP. Then again, I really do not need any new hardware really. I just like getting hardware, especially when it comes with a possible 8G of RAM.

One hope of mine is to return to the UK with my family, possibly moving there. My kids are still younger, so the impact on them would not be as bad as it would be had they been teenagers. Yeah I know it sounds odd for me to want to immigrate to the UK, but that is what I feel would be best for my family. I can not really explain it, just a feeling I have.

So much for the musings and ramblings I have done. Next post will be about some code stuff. Most likely going again in the vein of CakePHP.

So Long 2008

stephen — Wed, 31 Dec 2008 15:03:41 +0000

As the country starts in the festivities to lay to rest this past year, many people come up with lists, a la “10 Best Somethings of 2008″. Sometimes the lists even expand to 25. And if you are VH1 and MTV, with little to no viewership and the most horrible shows on earth (BTW, I thought MTV and VH1 were supposed to show music videos, novel concept for a couple of stations name Music Television and Video Hits 1), then your lists go to 100 and there is pointless commentary along with each number.

However, this is not the way I wanted to end 2008, with a list of something. I could list off many things:
10 biggest mistakes in 2008
10 best code tips of 2008
10 best sites of 2008
10 worst stories of 2008

Or I could just say that this past year has been a great learning experience for me. From all the things that have troubled me this past year, to the successes, not-so much successes, illnesses, code projects completed, and what not. Just like my last post, there is always something to learn. This past year was a great year to learn many lessons. Some lessons I hope to never go through again, as the learning part was very painful and unpleasant.

But now as the new year is coming along, many people will make promises to themselves they will promptly break. My only real New Years resolution is to take down this Christmas Tree in my house. I do that, and this next year will be a success.

There are a few different code projects I am looking to complete this year. I also want to go back to school and learn some more. I want to get better at all aspects of the languages I use, better at security and performance to anticipate threats coming in 2009, and as DSL/Cable speeds up in America (about time freakin A) tune the applications to perform better and not lose functionality. I want to also learn Russian. I know a little, but I would really love to be able to write and speak it fluently. Maybe even Spanish and French as well. I also want to learn to play the piano. I know how to read music, now I ought to put that to use.

And I can never forget my kids. I love them so much. I am really glad I am able to be around them, and I want to be able to help them out, play football with them, and just be the best dad I can be.

So, thank you for all the memories 2008. Thank you for all the lessons as well. Hopefully 2009 comes in with success and prosperity for all.

Never Pass up the Opportunity to Learn

stephen — Wed, 17 Dec 2008 19:02:50 +0000

Just a quick post, as this is now December and I have not posted for almost a month. But this is another simple, and easy, and sometimes forgotten idea among the web programming world. Never pass up the opportunity to learn something new. I know this sounds really easy, and possibly even like a “duh” comment. But there are so many times I come across people from all areas of life, and all areas of business who think that they have nothing new to learn. When they encounter something they have not done before, or something that is done different than the way they did it, then it is wrong, and it is not right, and it is not correct, that it needs to be scrapped and how much they could do it better. Now while this may sometimes may be the case, it usually is not.

Just because something is different, or there is a requirement to do something in a different way, then it does not mean it is wrong, it is just an opportunity to learn. On Twitter, I started to follow PHP Advent. There are many ideas presented in this that provide a great perspective. Some I would not have tried, just because I would not have thought of that approach. But I would not dismiss them just because of that. There is always something new to learn. Never “poo-poo” anything just because you are not familiar with it.

OK, soapbox post is complete.

New Theme for this site

stephen — Sun, 17 Aug 2008 02:56:26 +0000

I redid the theme for the site, and moved it to 2.6.1. I am not going to even remotely claim that this is a visually pleasing site, nor will I ever claim it will win for the best site design. However, what made me change it was that I was not exactly enamored by any of the themes, and decided to do one myself. I looked for how to do this, as I have messed around with Photoshop before, and have become brilliant at hacking things around in Photoshop. But I took a few tutorials on how to do some stuff. This design is based from those tutorials. For those who would like to know, I went to these sites:

That was just some of them. I may do more, but I am also teaching myself Objective-C/Cocoafor the Apple/iPod/iPhone. But if there are any good links out there for Apple tutorials, let me know, because I may just be Googling the wrong phrases.

AJAX and YUI

stephen — Mon, 11 Aug 2008 13:53:17 +0000

With the sensationalized aura surrounding this “web 2.0″ myth, there is more and more of a call for AJAX enabled sites. This demand gets higher due to sites like Facebook, MySpace, Twitter, and so forth. So when going forward with a design to implement AJAX libraries, which one is the best. The answer: Whichever one fits the job at hand. There are good points to Scriptaculous, jQuery DoJo and others. There is a good list of some of these with pros and cons at The Chandler Project, and a further list of other libraries at eDevil’s Weblog.

The one I am going to cover is a newer one, and one that is hosted elsewhere, which has its own pros and cons, and that is the Yahoo User Interface, or YUI. The documentation, the downloads (if you desire), tutorials and other information is located at http://developer.yahoo.com/yui/ and is very extensive for the different aspects it can do. What I am going to cover is something useful for long pages of content on the web, Tabbed Viewing.

Tabbed viewing allows for a load of content, to be displayed parts at a time, then when a user needs the next piece of information, they can click on a tab, and then new content is available without having to reload the page. The YUI provides great tutorials for these, and examples, with code. It is located at: http://developer.yahoo.com/yui/examples/tabview/index.html. Since the web is polluted with duplicates, I will not do that, but will instead show what I have done with this. I used the “build from markup” path on this one.

First you have your content. Now if this was really long content, we could break this up in 4 tabs. We would add the YUI libraries to be used, the following needs to be included:

In order to do dynamic loading, dynamic tab building and loading, there needs to be more libraries called, and you can see that in the YUI reference pages.

Now comes the styling. Since not every page will need to styled the way Yahoo! thinks it should be, I found some tags that I have replaced with inline CSS.

By resetting these, it will overwrite the styles for the tabs, the content area and the hover properties. Again, if you are fine with the Yahoo! method, that is fine. If not, these tags should help you on your own theme style.

It is important to ID the tab area DIV tag what you call out in the TabView() method. Add DIV tags to surround the tabbed area to set up a “boundary”. And then add the DIV tag for the tabbed area to be placed inside.


    
         ALL CONTENT WOULD GO HERE

Now the tabs. The tabs are UL and LI elements styled up. They are the first things in the DIV ‘content_area_name’ tag.


    Content One
    Content Two
    Content Three
    Content Four

You can choose which tab shows up first by adding the “selected” class to the LI tag. The EM tags are important to provide the padding and the spacing for the tabs. If you choose to leave those out, the text in the tabs will have no spacing and the tabs will lose some of their styling.

Now we add a DIV tag to show the content area for each tab, then a DIV tag with the ID of the href listed above for each tab section.


    
    CONTENT GOES HERE
    

    
	CONTENT GOES HERE
    

    
	CONTENT GOES HERE
    

    
	CONTENT GOES HERE

We need to include the script to call out the DIV area for the tabbed events, and content in these tabs.

And that should create the tabs, content is now available and will load the different tabs without reloading the page.

The entire code would look like this now:
















    
        
            Content One
            Content Two
            Content Three
            Content Four
        

        
	    
	    CONTENT GOES HERE
	    

	    
            CONTENT GOES HERE
	    

	    
	    CONTENT GOES HERE
	    

	    
	    CONTENT GOES HERE

You can put all of the code inside the BODY tags, and sometimes you have to based on templates being used. Or you can take the CSS, JavaScript calls, and inline styles, put those in the HEADER tags, and put the rest in the BODY tags.

Here are a couple of sample pages with the YUI Tab View, both in their styles, and in the new style listed above.

YUI Styled Tab View

Custom Style Tab View