OpenEuphoria

1. programming style

• Posted by Tone Škoda <tskoda at email.si> Oct 25, 2004
• 681 views
• Last edited Oct 26, 2004

I developed this programming style which made my coding much easier:
I comment blocks of code. And I make it so that it is clear for which block of
code the comment is for. Blocks of code and their comments can be organized in
tree. This style is especially useful if you write complicated code. If I didn't
use this style then coding complicated things would be a nightmare.

--//
--// Comment:
--//=>
    ...here is block of code...
    ...here is block of code...
    ...here is block of code...
...other code continues here...


Here's a real example:

--// Converts 'potentn_workobj' to work object and adds
--// it to 'All_work_objects'.
--// Updates global variables 'All_work_objects', 'Potent_workobjs'
--// and sometimes 'Final_objects'.
procedure add_wobj (POTWOBJ potentn_workobj)
    TOP_WOBJ new_wobj
    TOP_WORK_OBJECT_IDX new_wobj_idx
    TOP_WOBJS_IDXS new_wobj_neighs_idxs
    TOP_WOBJ_IDX child1_wobj_idx
    TOP_WOBJ_IDX child2_wobj_idx
    TOP_WOBJ_IDX cmp_child1_wobj_idx
    TOP_WOBJ_IDX cmp_child2_wobj_idx
    POTWOBJS_IDXS remove_potwobjs_idxs
    POTWOBJS new_potent_workobjs
    --//
    --// Update 'All_work_objects':
    --//=>
        new_wobj = convert_potwobj_to_wobj (potentn_workobj)
        All_work_objects = append (All_work_objects, new_wobj)
    --//
    --// Update 'Potent_workobjs'.
    --// We only need to check those potential work objects,
    --// which are made of work objects whose neighbour changed,
    --// ie who have new neighbour 'new_wobj',
    --// AND those potential work objects which 
    --// were made of work objects which were part of
    --// 'potentn_workobj'.
    --//=>
        --//
        --// Get indexes of work objects which need to be checked:
        --//=>
            new_wobj_neighs_idxs = get_work_obj_neighs_indexes (new_wobj)
            child1_wobj_idx = potwobj [POTWOBJ_CHILD1]
            child2_wobj_idx = potwobj [POTWOBJ_CHILD2]
            new_wobj_idx = length (All_work_objects)
            if Debug then
                assert (equal (All_work_objects [length (All_work_objects)],
                    All_work_objects [new_wobj_idx]))
            end if
        --//
        --// Remove old:
        --//=>
            --//
            --// Get 'remove_potwobjs_idxs':
            --//=>
                remove_potwobjs_idxs = {}
                for i = 1 to length (Potent_workobjs) do
                    cmp_potwobj = Potent_workobjs [i]
                    cmp_child1_wobj_idx = cmp_potwobj [POTWOBJ_CHILD1]
                    cmp_child2_wobj_idx = cmp_potwobj [POTWOBJ_CHILD2]
                    if cmp_child1_wobj_idx = child1_wobj_idx
                    or cmp_child1_wobj_idx = child2_wobj_idx
                    or cmp_child2_wobj_idx = child1_wobj_idx
                    or cmp_child2_wobj_idx = child2_wobj_idx
                    or find (cmp_child1_wobj_idx, new_wobj_neighs_idxs)
                    or find (cmp_child2_wobj_idx, new_wobj_neighs_idxs) then
                        remove_potwobjs_idxs = append (remove_potwobjs_idxs, i)
                    end if
                end for
            --//
            --// Remove:
            --//=>
Potent_workobjs = remove_members (remove_potwobjs_idxs,
                Potent_workobjs)
        --//
        --// Add new:
        --//=>
            --//
            --// Get 'relink_wobjs_idxs':
            --//=>
                relink_wobjs_idxs = new_wobj_neighs_idxs
                relink_wobjs_idxs = append (relink_wobjs_idxs, new_wobj_idx)
            --//
            --// Get 'new_potent_workobjs':
            --//=>
                TODO
            --//
            --// Add:
            --//=>
Potent_workobjs = sorted_seq_insert (new_potent_workobjs,
                Potent_workobjs, Potent_workobjs_cmp_routid)
    --//
    --// Update 'Final_objects':
    --//=>
        TODO
end procedure

3. Re: programming style

• Posted by Patrick Barnes <mrtrick at gmail.com> Oct 26, 2004
• 633 views

The way I comment things:
If a function does things in an orderly fashion (which most of mine do)

    #code#
--1. what this block does (in general terms)
--==============================
    --1.1 what this sub block does 
   #code#
          --what this small section does
          #code#  
          #code#
    #code#
   
    --1.2 what this sub block does 
    #code#  ---what this line does
    #code#  
    #code#  

--2. what this block does (in general terms)
--==============================
etc...

Of course, the granularity of the subheadings is generally high - when
it gets down to the nitty-gritty, there's small comments in places
where code may be difficult to understand (eg  combining 3 subslices
of odd sequences given index values stored in other sequences) saying
what it does.

The high-level headings and subheadings tell you what the code is
doing. It's much easier to look at a 5-line section of code, knowing
what just that section does, than looking at a 50-line function,
knowing in general terms what the whole things does.





-- 
MrTrick

5. Re: programming style

• Posted by Matt Lewis <matthewwalkerlewis at yahoo.com> Oct 26, 2004
• 693 views

Tone Škoda wrote:
> 
> Too much comments is not good. But commenting blocks of code and routines is
> sometimes
> neccesary, especially in euphoria, which needs more comments than C++. It
> seems C++
> was made so that all things are already commented with code.
> 

I agree.  C++ is kind of like Perl that way.

Matt Lewis