Wednesday 23 Apr 2008

Good coding presentation

The code presentation in any language is a very important point to increase comprehension and "visual" resarch. At the moment and when we re-read a few weeks, or months later, a good presentation can make the diffrence between a fast developper and a laming one. ;-)

Of course, a very important element is the tabulations (some people prefer spaces to be sure to keep the same space on diffrent machines). You must take care of well staging the various levels. Especialy in PHP where HTML code can interlace PHP, keep the good number of tabulation for PHP (it's less important for HTML). You will only need to follow the column to find "where you are".


I often see developpers present the braces { } without align them. Even if it becomes more and more a rule, it's a mistale! We don't pay for one more line, it's not like a sheet of paper. :-p

Take care of well aligning the opening and closing braces.

This is even true in CSS file where we only have one (or 2) braces levels. If some other person modify your code some times later (it may be you), will thank you.

Bad:

while (...) {
  if (...) {
    ...
  }
}

Good:

while (...)
{
  if (...)
  {
    ...
  }
}

When we have several braces levels, a code editor like NotePad++, allows you to immediatly see the matching braces with a vertical guide. And even without this guide, you'll see it's faster to correct a brace error visualy.

In my simple example, if I miss the opening brace after if, I can't see it quickly if they are not aligned.


Another usually made mistake, is to compress to much the code. Once again, we don't pay like on paper, it's not a book, nor a draft. Keep 3 or 4 blank lines between 2 functions or 2 distinct parts.

Use commentaries, introducing the next part, ou just to separate.


/* End of my big function. */
or
/*************************/
or
/* ------------------------- */

Even if you will never automaticaly generate documentation with Doxygen, you can use its syntax for important commentaries because it's clear and visual.


/**
 * The next part is for printing.
 * Each line is first exploded,
 * then tweaked, and printed.
 */


Some examples of utility of a good presentation with NotePad++
Notepad++ screenshot 1Notepad++ screenshot 2Notepad++ screenshot 3


cafĂ© Did this article help you? 
Buy me a coffee!

3 answers at “Good coding presentation”

  1. 1
    Chad (scriptasy.com) said:

    http://azur-dev.kizone.net/fichiers/notepad-capture-1.gif

    Suppoted? :P

  2. 2
    David (azure-dev.kizone.net) said:

    Haha! I never read the text in the screenshots! :mrgreen: They come from Notepad++ site.

    PS: The banner on your site is very cool. ;-)

  3. Backlink from reading comprehension

Leave a comment (all comments are moderated, don't waste time with spam)

Azure Dev