-*- outline -*-

                /*---------------------------------------.
                | Coding style of Unified Test Tool Kit  |
                `---------------------------------------*/

     /*------------------------------------------------------------------.
     | This document consists of a set of rules which must be respect by |
     |      every maintainers of Unified  Unified Test Tool Kit.         |
     `------------------------------------------------------------------*/


* Introduction

  This  text  deals with the norm applied to all official Unified Test Tool Kit
source  files  included in the distribution. Everyone who write a peace of code
into Unified Test Tool Kit must follow the rules below.
  Every  rules  mentioned below are not about the layout of uttk's source file.
In  this document some part of the ruby's standard library may be forbidden and
some  features  of  Ruby  too.  We  do so for stability/security and efficiency
reasons.
  If  you  want to add a rule to this file you have to justify it with at least
one  strong and objective argument. Any subjective rules will not be allowed in
this  document.  The  summary  of  every  rules  must  be  scared to allow fast
reading.

* Coding style rules

** String evaluation

     /*--------------------------------------------------------------.
     | You have to use the double quoted string the least possible.  |
     `--------------------------------------------------------------*/

  Ruby  has  two  level  of  string evaluation: double quoted string and single
quoted  string. The single quoted version is faster since less substitution are
allowed  by  Ruby.  So,  as  soon as, you do not need a full evaluation of your
string you have to use the single quoted version for efficiency reason.

** Logger utilization

      /*------------------------------------------------------.
      | You have to write your log messages using the block.  |
      `------------------------------------------------------*/

  Ruby's  logger  provides  two  ways  to write your log messages. You can pass
your  log  string  to  the  logger  either as a function argument or as a block
which  return a string. The second version is prefered since the block, thought
the  string,  will not be evaluated by Ruby if the log level severity is higher
than  the  level  of  your  message.  This  way,  time is saved for every debug
messages when your severity level is fatal, for instance.

** Using blocks

          /*----------------------------------------------.
          | Do not use yield, block_given?, iterator?     |
          | block.call (but []) and try minimize block[]. |
          `-----------------------------------------------*/

*** Do not use yield

  Ruby provides sevral ways to use blocks, and we retain the most efficient.

  Examples:

    # Bad                               | # Good
                                        |
    class A                             | class A
      def each                          |   def each ( &block )
        @a.each { |k, v| yield k, v }   |     @a.each(&block)
      end                               |   end
                                        |
      def each_key                      |   def each_key ( &block )
        @a.each { |k, v| yield k }      |     @a.each_key(&block)
      end                               |   end
                                        |
      def each_value                    |   def each_value ( &block )
        @a.each { |k, v| yield v }      |     @a.each_value(&block)
      end                               |   end
    end                                 | end


*** Try to minimize block.call or block[]

    # Bad                               | # Good
                                        |
    def each2 ( &block )                | def each2 ( &block )
      @a.each do |k, v|                 |   @a.each(&block)
        block.call(k, v)                | end
      end                               |
    end

*** No block_given? nor iterator?

  Since we do not use yield, block_given? and iterator? are useless.
  Example:

    def foo ( &block )
      if block  # instead of block_given? or iterator?
        ...
      end
    end

    def foo ( &block )
      if block.nil?  # instead of not block_given? or not iterator?
        ...
      end
    end

*** No block.call but block[]

  The methods [] and call are aliases. But the [] one is closer to a real
  function call.

* Layout rules

** Try to respect the orginal style

** No Tabulations

  Don't  use  tabulations. They pollute the code since editors and/or users are
not  agree  on  the  width of a tabulation. Tell your editor to replace them by
spaces. Expect in the ChangeLog which is handled automatically by Vcs.

*** Vim
  Just type (or add it to your .vimrc): `:set expandtab'

*** Emacs
  FIXME: FILL ME

** No trailling whitespaces

  Do not let trailling whitespaces in your files !!!

** Newline required at the end of file

  Do not let last line of file without a newline !!!