OpenEuphoria

Re: Commentary Convention: Prolog

• Posted by Marcel Kollenaar <M.Kollenaar at SLO.NL> Oct 09, 1996
• 2094 views

Hi, Lucien,

You wrote:
> ill be first in the barrel with the following PROLOG commentary
> model.  i keep this in \euphoria\include\prolog.mdl and when
> creating a new program, i copy it into the new file and begin
> finding and changing the ?'s.  granted, this is a bit much for a
> one man shop to keep properly updated (who among us is
> not just a bit lazy when it comes to documentation?)..

agree

The model you describes is likewise mine. It's comming from years of
programming in WP5.1 macro language and is not so detailed as your
PROLOG version. I'll stick to yours and sqeezed it a little. I do
everything with macro's in the WordPerfect program editor
(Modes: DOS/BIN/SHM/WPM/EDM).

> -- * Company     : ?company_name
> -- * File        : ?filename.ext
> -- * System      : ?system_title
> -- * Component   : ?component_title
> -- * Written by  : ?author
> -- * Date        : ?m/dd/yy
> -- * Copyright   : ?who owns the copyright to this program & since when
> -- * Description : ?brief functional description of this program
> -- * External Functions:
> ? list of externally defined functions (may also be include
>   statements)
> -- * Internal Functions:
> ? list of internally defined functions
> -- * Global Variables Defined:
> ? list of global variables/constants defined in this program
> -- * Global Variables Used:
> ? list of global variables/constants used in this program
> --------------------------------------------------------------------
> -- * MODIFICATION HISTORY    BY      DATE
> -- * ?                       ?       ?m/dd/yy
> -- BEGIN CODE

Because I am a chaotic person I need some strictly rules to work
along.

Naming conventions:
I keep them simple. For identifiers I use the startletter of the type
'a' for atom, 'o' for object and so on. I saw it in some Euphoria
code so I used it likewise, thanks to him who introduced it. Then I
capitalize identifiers wordlike: oTreePage, sIndexHeader. The names of
functions are sReadIndexHeader(). This means that the function
returns a sequence and so on. I haven't yet made my mind up if I like
the underscore in names or capitalize the words: s_read_index_header
or sReadIndexHeader??? Anyone can influence me.

Comment in functions/procedures: I like to construct sentence like
comment, reading them from left to right an top down after the --.

function look(sequence s, -- looking in string s
              atom k,     -- for k
              integer t)  -- after t skips
-- Descr  : look at intervals through sequence s
-- Returns: {SUCCES,element}
-- Comment: -
-- Start of code
   ...
end function--look

I took over the capitalization of constants.
constant TRUE  = 1,
         FALSE = not TRUE

I hope there will be a lot of others programmers who will share there
experiences and complete this tiny list. Maybe this will result in
conventions for writing Euphoria programs. At the end I want to
reference the "share-ability" tips of Rob Craig from RDS in mail
"Coding conflicts in Filelist.e".

Marcel Kollenaar
M.Kollenaar at slo.nl