Re: Commentary Convention: Prolog
- Posted by Marcel Kollenaar <M.Kollenaar at SLO.NL> Oct 09, 1996
- 2040 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