I was wondering around on the big wide scary web and saw a lot of badly written comment for code so I thought it shouldn’t be bad to give a little overview on how comment should be written, at least how I think it should be written.

Not all comments can be written in the same way and not all comments can be read by other programs but I personally think the Java comment is the most readable one, and (huge advantage) can be read by the Javadoc processor. When writing in PHP this is done in the same way as PHPDoc is an adaptation of Javadoc.

So write your comment like this:

/**
 * This is a basic description of your method,
 * write down here what the function does in general
 *
 *@param integer $id
 *@return array Array of objects
 *@author Kenneth van Rumste
 */

As you can see we have the general description of a method first, written in a few words. Only write more if this is really necessary. Comments are there to help when the developer doesn’t understand the code and everybody should keep in mind that the name of a method should contain the basic information about what’s happing inside. For example don’t use methodName1 for a method, but retrieveDailyUsers to select the daily users. So you don’t need a lot of extra comment to explain what is happening, Jeff Atwood (Coding Horror) wrote a great post last year on the usage of comments.

In the second part you can see a bunch of tags added into the comment, these are very handy when writing code as they inform parsers how to display documentation and allow IDE to define variable types.

I added only the basic data to the comment and a lot more tags can be added but as I m a lazy guy you can check them all out here.

To finish this post let us take a look at some of my all time favorite, comment jokes

stop(); // Hammertime!

Catch (Exception e) {  
//who cares?
}   

Exception up = new Exception("Something is really wrong.");

throw up;  //ha ha   

doRun.run();  // ... "a doo run run".   

long long ago; /* in a galaxy far far away */   

/////////////////////////////////////// this is a well commented line

//Abandon all hope yea who enter beyond this point   

//Woulda
if(x) {}
//Shoulda
else if(y) {}
//Coulda
else {}   

/* This isn't the right way to deal with this,
but today is my last day, Ron just spilled coffee on my desk,
and I'm hungry, so this will have to do... */
return 12; // 12 is my lucky number   

#define TRUE FALSE //Happy debugging suckers   

// TODO - Comment this function

Ever heard of ‘less is more’? This is, more than ever, a standard that every developer should follow while designing his new website. Why the f* would I start talking about that, you can ask yourself. Well, the answer is quite simple, as I was going to the toilet earlier this day and was in deep thoughts with the question: why isn’t everything designed and created as simple as a toilet room?

This is one of the only rooms and spaces in the world where you only find exactly what you need for the job and nothing else. No rubbish, no extra stupid information, just 3 simple things: a toilet, toilet paper and a little sink to wash your hands. These 3 things can easily be compared to 3 actions: brew, act, finish.

The same structure should be kept in mind when creating a website. Each page should contain only the information exactly needed without mixing up different parts together to one big pile of sh*t. Users don’t find the good or simplest way to the data they need. You would think that this is a very simple rule, but a lot of designers and organizations seem to forget this, so please, take your time while designing.

How can you do that?

A good idea doesn’t mean that your site will be a great success; you have to think it trough. You can start by taking your time to do a good analysis of the idea, work out the big lines before thinking of the details. Write down the major goals of the site and use them along the way to stay on the correct path. Split your site up into 5-6 major pieces as they will be the menu of your site, and be sure that this is a good structure. There is nothing more annoying for a developer then changing of big parts as they are in code named the same way.

For example, if one part of your site is called ‘Contact’, and after 3 months of development you decide to call this part of the site ‘About’, all code that the viewer doesn’t see will still be referred to as Contact.
2 options for a developer in this case, you can stop bothering yourself and don’t do any changes or change all contact to about, spend a lot of time doing this, but get a better result. I guess you see the picture why this is important.

In the frontend (for designers) this is actually the same story. Try to create a view (without design) where you should place every part, and be sure about the positioning, as this is very frustrating for a designer if this changes after designing the layout. A template and/or layout is often created for or in function of specific parts on each page, so if they are replaced, your page could easily get another layout and impression.

Try to put only the necessary content on each page, the only thing that can be put in a page besides the data are links to other parts of the site. Don’t put products on about pages; don’t put contact information on a product page. If I wanted the contact information, I would’ve clicked the contact button.

Try to keep these things in mind as they will ease up the path to a simple, clean website and only correct data will be displayed because: less is more!!!