OpenEuphoria

How would you document a project, such as you were making a game in Euphoria,
how would you document it something like this:
#include necssary files
#clear screen

something like that, can I get a little more help on documenting a project

2. Re: Document A Project

• Posted by Greg Haberek <ghaberek at gmail.com> Feb 18, 2005
• 531 views
• Last edited Feb 19, 2005

> How would you document a project, such as you were making a game in Euphoria,
> how would you document it something like this:
> #include necssary files
> #clear screen

What helps me in bigger programs is to explain what each routine does
right after I declare it, then follow that logic with little comments.
That's pretty much how all my code ever looks. Although for
distribution, I have a little utility that strips any comments
starting on the first line, which helps reduce the size of my files.
(Sometimes over 1/2 my code is comments, heck look at Win32Lib, it's
nuthin but comments!)

Example: (I'm using this in an app I'm writing)

global function dayOfWeek( integer pMonth, integer pDay, integer pYear )
--  This function determines the day of the week given
--  a date in the form Month, Day, Year. I believe this
--  formula may be more accurate than Junko's, or I'd
--  be using Junko's instead. :)
--
--  Step 1: Take the last two digits of the year and add 1/4.
--  Step 2: Determine month code.
--  Step 3: Add year, month code and day
--  Step 4: Take remainder of seven.
--
--  The result is the day of the week (starting with Monday)

    integer lCode, lResult

    -- subtract 100 until pYear is less than 100
    while pYear > 100 do
        pYear -= 100
    end while

    -- add 1/4 to the year
    pYear += floor( pYear / 4 )

    -- determine month code, MONTH_CODE
    -- is declared else where in our code
    lCode = MONTH_CODE[ pMonth ]

    -- add the values
    lResult = pYear + lCode + pDay

    -- get remainder of seven and add 1
    lResult = remainder( lResult, 7 ) + 1

    return lResult
end function

~Greg

Perhaps I was not clear on what I said. If you were writing down code on paper
how would you write it down?

4. Re: Document A Project

• Posted by rudy toews <rltoews at ilos.net> Feb 19, 2005
• 537 views

Andy wrote:
> 
> Perhaps I was not clear on what I said. If you were writing down code on paper
> how would you write it down?
> 

you don't seem to want the programmers documentation that helps in future
software updating.  Are you refering to a user's manual by chance?

i would write program code or user's manual as if i were writing to a
great grandparent who never seen a computer.
in outline form to start with, followed by more detail.
let someone else try to follow it and write down their questions.
maybe the format could even be in question answer format.

just a thought
rudy

Andy wrote:
> 
> Perhaps I was not clear on what I said. If you were writing down code on paper
> how would you write it down?
> 


i use the outline format to help prioritize the variables and routines.
try to use few global variables.
have routines pass arguments to each other often.
routines should do only one thing , not too many things at once(easier said
thandone).

if the routines are general enough for other apps , put them into their own
library that can then be included in other apps.
collect routines that are app specific into their own lib. then you don't
have to see the main code when updating the app.

hope this helps
rudy

6. Re: Document A Project

• Posted by Greg Haberek <ghaberek at gmail.com> Feb 19, 2005
• 567 views

> Perhaps I was not clear on what I said. If you were writing down code on paper
> how would you write it down?

Well, there's two different ways I've used: Flow-charts and Pseudo code.

Flow charts are fun. I had a whole 1 year class on flowcharting in
high school. Flow charts are better for languages like COBOL, RPG and
BASIC. I haven't had much luck with flowcharting in Euphoria, and I
don't even know if anyone uses flowcharts any more. But whatever you
do, don't lose your flow chart stencil!! (They won't give you another
one.)

Pseudocode is a way of "talking-while-programming" as one of my
professors once put it. This allows you to be fairly generic while
still hold the form and logic of programming. Its also how I jot down
code if I'm sitting in class and something comes to me. I also draw
out window layouts on blank paper first, *in pencil*.  Its a lot
easier to have a visual reference when you're building a window.

this:

<pseudocode>
-- generic file input routine
Declare 'data' as a sequence
Declare 'line' as an object
Declare 'fn' as an integer

Open 'fn' for reading

If fn is -1 then
    Die.

Intialize data to an empty sequence.

Read a 'line' from 'fn'

While 'line' is a sequence
    Append 'line' to 'data'
    Read another 'line' from 'fn'

Close 'fn'

Output 'data'
</pseudocode>

turns to this:

-- generic file input routine
--Declare 'data' as a sequence
    sequence data
--Declare 'line' as an object
    object line
--Declare 'fn' as an integer
    integer fn

--Open 'fn' for reading
    fn = open( "somefile", "r" )

--If fn is -1 then
    if fn = -1 then
--    Die.
        puts(1, "could not read somefile\n")
        abort(1)
    end if

--Initialize data to an empty sequence.
    data = {}

--Read a 'line' from 'fn'
    line = gets( fn )

--While 'line' is a sequence
    while sequence( line ) do
--    Append 'line' to 'data'
        data = append( data, line )
--    Read another 'line' from 'fn'
        line = gets( fn )
    end while

--Close 'fn'
    close( fn )

--Output 'data'
    pretty_print(1, data, {})

Greg Haberek wrote:
> 
> > How would you document a project, such as you were making a game in
> > Euphoria,
> > how would you document it something like this:
> > #include necssary files
> > #clear screen
> 
> What helps me in bigger programs is to explain what each routine does
> right after I declare it, then follow that logic with little comments.
> That's pretty much how all my code ever looks. Although for
> distribution, I have a little utility that strips any comments
> starting on the first line, which helps reduce the size of my files.
> (Sometimes over 1/2 my code is comments, heck look at Win32Lib, it's
> nuthin but comments!)
> 
> Example: (I'm using this in an app I'm writing)

I'm going to make a menance of myself here, but in my opinion Greg, the
type of documentation you give as an example here is a good example of
how not to document source code.

Let me explain ... the purpose of source code documentation is to help
a reader understand your aspirations and motives for the fragment
you are documenting. Do not call English descriptions of *what* the code
is doing, documentation.

> }}}
<eucode>
> global function dayOfWeek( integer pMonth, integer pDay, integer pYear )
> --  This function determines the day of the week given
> --  a date in the form Month, Day, Year. I believe this
> --  formula may be more accurate than Junko's, or I'd
> --  be using Junko's instead. :)
> --
> --  Step 1: Take the last two digits of the year and add 1/4.
> --  Step 2: Determine month code.
> --  Step 3: Add year, month code and day
> --  Step 4: Take remainder of seven.
> --
> --  The result is the day of the week (starting with Monday)
This line above needs a bit more detail to be helpful. Something like ...

  -- The result is an integer from 1 to 7, where 1 represents Monday,
  -- 2 is Tuesday, and so on until we get to 7 for Sunday.
 
>     integer lCode, lResult
> 
>     -- subtract 100 until pYear is less than 100

Okay, I read the code and see that this is what you are doing, but *why*
are you doing it? What are you trying to achieve by doing this?

How about this sort of thing instead ...

      -- The algorithm only needs the last two digits of the year
      -- so we remove the 'century' part, if any, of the supplied year.
>     while pYear > 100 do
>         pYear -= 100
>     end while
BTW, we could have done this in one line ...

      pYear = remainder(pYear, 100)


>     -- add 1/4 to the year
Again, I can read the code and you have accurately described what it is
doing, but why is it doing this?

>     pYear += floor( pYear / 4 )
> 
>     -- determine month code, MONTH_CODE
>     -- is declared else where in our code
Why? And how is it declared elsewhere? 

>     lCode = MONTH_CODE[ pMonth ]
> 
>     -- add the values
Duh! Yes, that's what the code does, but why?

>     lResult = pYear + lCode + pDay
 
>     -- get remainder of seven and add 1
Again this is an accurate description of what the code is doing. But I
don't have a clue why? How would I know if this code is right or not?
Why '7'? Why add one?

      -- Having calulated the number of days we now divide this into
      -- weeks and the left over amount is the offset into a week. We
      -- add one to convert the offset into an index, which is then
      -- returned to the caller. 
>     lResult = remainder( lResult, 7 ) + 1
> 
>     return lResult
> end function
> </eucode>
{{{


Sorry to be so harsh, but I'm a bit "thingy" about improving the readability
of source code. I get very tired of seeing "waste-of-space" type 
documenation ...

    -- add one to result
    result += 1

Don't take it personally, okay 

-- 
Derek Parnell
Melbourne, Australia
irc://irc.sorcery.net:9000/euphoria

8. Re: Document A Project

• Posted by Derek Parnell <ddparnell at bigpond.com> Feb 19, 2005
• 527 views

Andy wrote:
> 
> How would you document a project, such as you were making a game in Euphoria,
> how would you document it something like this:
> #include necssary files
> #clear screen
> 
> something like that, can I get a little more help on documenting a project

First, write down what you want the project to achieve. This should only
be three or four lines. It is a high level "goal" document. It helps you
keep on track and to know when to stop. Get somebody else to read it and
suggest improvements.

Next, write down some background or contextual information about the 
problem that the project is trying to solve. Define the problem domain
jargon in terms that anyone can understand. For a game, you might like
explain what the terminology is about, etc...   Get somebody else to read it and
suggest improvements.

Next, write down the 'business requirements'. By this I mean, a list of
rules that the project *must* implement. These are typically *very* short
statements (a sentence or two), and usually take the form of ...

 #0001 The system must validate all user input before storing it in any
       database.
 #0002 The customer id must be exactly 6 digits long.
 #0003 Each customer must have a unique id. That is, no two customers can
       ever have the same id.

Give each rule a number. This will help you trace the requirements into
other documents and the source code. These rules also form the basis of
unit test cases.  Your will no doubt have hundreds of rules in the end.
Get somebody else to read them and suggest improvements.

Next, design the test cases that will help prove that your programs are
working per specification. You migh also do some preliminary use-cases here
too.  Get somebody else to read these and suggest improvements.

Next, analyse the requirements and come up with a plan/design about how they
could be implemented in software. Define your algorithms here. Map out
your process flows (tools to use: flowcharts, dataflows, use-cases, etc...)
Get somebody else to read it and suggest improvements.

Next, write some prototypes to test your algorithms and design ideas. This
often leads to redefining (or clarifying) the requirements.  Get somebody
else to read it and suggest improvements.

Now you can create some pseudo-code for each of the programs you will be
writing.  Get somebody else to read them and suggest improvements.

Next, code the programs so that they follow the designs you have made. Test
them often -- say every 10-15 minutes of coding.  Get somebody else to read
your source code and suggest improvements.

Next, run your test cases and go back to fix up things. That might mean
fixing requirements, design and/or source code. 

All through this process, the end user documentation needs to be worked on.
Do not leave until you have finished the testing. Most the user docs should 
me written while designing the system, that is before coding the programs.
Get somebody else to read your user docs and suggest improvements.


And this is the 'short' version of project development 101.

-- 
Derek Parnell
Melbourne, Australia
irc://irc.sorcery.net:9000/euphoria

> Don't take it personally, okay 

I completely understand. I think that I mostly document for me, like
taking notes in my code for later reference. I've been doing a lot of
studying of Win32Lib, IDE and some other apps and such, and I think
I'm getting better on my commenting. Heck, six months ago I barely
even put comments at all!

~Greg

10. Re: Document A Project

• Posted by don cole <doncole at pacbell.net> Feb 19, 2005
• 539 views

I like to document my projects in three different steps.

1.Input
2.Number crunching
3.Output

Don Cole
SF

Andy wrote:
> 
> If you were writing down code on paper
> how would you write it down?
> 


Last two programs, Multisearch and Resizer, i wrote on paper, because i find it
easier to think that way, i tend not to complicate so much.

first it should be at least a little clear in your head. then go writing.
i first define (draw) user interface (if any) and global variables and their
structure (for this for me C structures are much easier that Eu sequences).
global variables should be commented, and return values of functions, and which
global variables routine modifies, other things only if confusing or not obvious,
because it saves you time and important comments are that way more easily
visible. if there are too much comments its hard to keep them in sync with code
they comment. its best if code comments itself (again for this C is better than
Eu, but Eu has many other advantages over C).

for routines: if they are complicated i do them like this:
on top of routine (inside) i write down neccesarry steps, then write actual code
for each step. like this:

-- step 1: explanation what to do

-- step 2: explanation what to do

-- step 3: explanation what to do


--1. <no need to write same comment here again.>
<CODE>

--2.
<CODE>

--3.
<CODE>



i dont write pseudo code, i just write in euphoria, except for very simple and
obvious things, then i use pseudocode. i leave out some un-important things so i 
dont have to write so much (local variables declarations, simple routines,...).

i write with pencil so that i can easily erase things with eraser.


i don't like to test my code during development (like i used to), i just like to
write all code (at least the most important), and then consciously reserve a lot
of time (few days) for debugging. that way debugging is more enjoyable :)
Independent routines and similar things i can test immediately, or write test
code down and test them in debug time.


also, leave hard problems and bugs for end, solve easy ones first.

12. Re: Document A Project

• Posted by CoJaBo <CoJaBo_EUforum_Address at CJBN.net> Feb 19, 2005
• 549 views
• Last edited Feb 20, 2005

Derek Parnell wrote:
> 
> Greg Haberek wrote:
> > 
> > > How would you document a project, such as you were making a game in
> > > Euphoria,
> > > how would you document it something like this:
> > > #include necssary files
> > > #clear screen
> > 
> > What helps me in bigger programs is to explain what each routine does
> > right after I declare it, then follow that logic with little comments.
> > That's pretty much how all my code ever looks. Although for
> > distribution, I have a little utility that strips any comments
> > starting on the first line, which helps reduce the size of my files.
> > (Sometimes over 1/2 my code is comments, heck look at Win32Lib, it's
> > nuthin but comments!)
> > 
> > Example: (I'm using this in an app I'm writing)
> 
> I'm going to make a menance of myself here, but in my opinion Greg, the
> type of documentation you give as an example here is a good example of
> how not to document source code.

I have a much better example of what NOT to do,
can anyone identify what this procedure was supposed
to do?
New comments shown in (). There was only 1 origanal
comment: --last.

int rvls
rvls=1
procedure resva(int s)
int rs,nv,e
nvcs=1--(Now what did this do...?)

nv=length(vs)
if s=0 then
	rs=1
	rvls=1
		if nv>nvcs then
			setEnable(vcsb,1)
			setScrollRange(vcsb,1,nv-nvcs+1)
		else
			setEnable(vcsb,0)
		end if
	
	for o=1 to nvcs do
		e=nv>=o
		if not e then
			setText(a[o][1],"")
			setText(a[o][3],"0")
		else
			rvls=1--(Why? it is already 1...)
		end if
		
		setEnable(a[o][1],e)
		setEnable(a[o][2],e)
		setEnable(a[o][3],e)
		setEnable(a[o][4],e)
	end for
elsif s=-1 then--last (last what?)
	rs=rvls
else
	rs=s
	rvls=s
end if
s=rs--(But s isn't used anymore?)

for o=0 to nvcs-1 do
if o+rs>nv then
	exit
end if
	
	setText(a[o+1][1],vs[o+rs])
	setText(a[o+1][3],sprint(vs[o+rs]))
end for
nvcs=0
end procedure

> 
> Let me explain ... the purpose of source code documentation is to help
> a reader understand your aspirations and motives for the fragment
> you are documenting. Do not call English descriptions of *what* the code
> is doing, documentation.
> 
> > }}}
<eucode>
> > global function dayOfWeek( integer pMonth, integer pDay, integer pYear )
> > --  This function determines the day of the week given
> > --  a date in the form Month, Day, Year. I believe this
> > --  formula may be more accurate than Junko's, or I'd
> > --  be using Junko's instead. :)
> > --
> > --  Step 1: Take the last two digits of the year and add 1/4.
> > --  Step 2: Determine month code.
> > --  Step 3: Add year, month code and day
> > --  Step 4: Take remainder of seven.
> > --
> > --  The result is the day of the week (starting with Monday)
> This line above needs a bit more detail to be helpful. Something like ...
> 
>   -- The result is an integer from 1 to 7, where 1 represents Monday,
>   -- 2 is Tuesday, and so on until we get to 7 for Sunday.
>  
> >     integer lCode, lResult
> > 
> >     -- subtract 100 until pYear is less than 100
> 
> Okay, I read the code and see that this is what you are doing, but *why*
> are you doing it? What are you trying to achieve by doing this?
> 
> How about this sort of thing instead ...
> 
>       -- The algorithm only needs the last two digits of the year
>       -- so we remove the 'century' part, if any, of the supplied year.
> >     while pYear > 100 do
> >         pYear -= 100
> >     end while
> BTW, we could have done this in one line ...
> 
>       pYear = remainder(pYear, 100)
> 
> 
> >     -- add 1/4 to the year
> Again, I can read the code and you have accurately described what it is
> doing, but why is it doing this?
> 
> >     pYear += floor( pYear / 4 )
> > 
> >     -- determine month code, MONTH_CODE
> >     -- is declared else where in our code
> Why? And how is it declared elsewhere? 
> 
> >     lCode = MONTH_CODE[ pMonth ]
> > 
> >     -- add the values
> Duh! Yes, that's what the code does, but why?
> 
> >     lResult = pYear + lCode + pDay
>  
> >     -- get remainder of seven and add 1
> Again this is an accurate description of what the code is doing. But I
> don't have a clue why? How would I know if this code is right or not?
> Why '7'? Why add one?
> 
>       -- Having calulated the number of days we now divide this into
>       -- weeks and the left over amount is the offset into a week. We
>       -- add one to convert the offset into an index, which is then
>       -- returned to the caller. 
> >     lResult = remainder( lResult, 7 ) + 1
> > 
> >     return lResult
> > end function
> > 

> 
> Sorry to be so harsh, but I'm a bit "thingy" about improving the readability
> of source code. I get very tired of seeing "waste-of-space" type 
> documenation ...
> 
>     -- add one to result
>     result += 1
> 
> Don't take it personally, okay 
> 
> -- 
> Derek Parnell
> Melbourne, Australia
> irc://irc.sorcery.net:9000/euphoria
> 


CoJaBo
"Error: Keyboard not present.
Press F2 to continue, F10 for setup." -- Old 486
[1010] << Supposed to be a computer
QWERTY
Laptop
Athlon 64 3700+ 2.4Ghz, 2GB RAM, 100GB HDD,
NVIDIA GeForce4 440 Go 64M Video card,
1920x1200 Resolution LCD

On Sat, 19 Feb 2005 12:37:47 -0800, CoJaBo <guest at RapidEuphoria.com>
wrote:

>I have a much better example of what NOT to do,
LOL. Good example. 100 lashes to whoever wrote that.
Fabulous choice of variable names to boot.
>can anyone identify what this procedure was supposed
>to do?
erm, scroll to/enable a column in a grid of some sort?

>nvcs=1--(Now what did this do...?)
move 1 to nvcs (SCNR 

>elsif s=-1 then--last (last what?)
erm, reactivate a column? ( wild guess, of course )

Pete

14. Re: Document A Project

• Posted by don cole <doncole at pacbell.net> Feb 20, 2005
• 535 views

> > > global function dayOfWeek( integer pMonth, integer pDay, integer pYear )
> > > --  This function determines the day of the week given
> > > --  a date in the form Month, Day, Year. I believe this
> > > --  formula may be more accurate than Junko's, or I'd
> > > --  be using Junko's instead. :)
> > > --
> > > --  Step 1: Take the last two digits of the year and add 1/4.
> > > --  Step 2: Determine month code.
> > > --  Step 3: Add year, month code and day
> > > --  Step 4: Take remainder of seven.
> > > --
> > > --  The result is the day of the week (starting with Monday)
> > This line above needs a bit more detail to be helpful. Something like ...
> > 
> >   -- The result is an integer from 1 to 7, where 1 represents Monday,
> >   -- 2 is Tuesday, and so on until we get to 7 for Sunday.
> >  
> > >     integer lCode, lResult
> > > 
> > >     -- subtract 100 until pYear is less than 100
> > 
> > Okay, I read the code and see that this is what you are doing, but *why*
> > are you doing it? What are you trying to achieve by doing this?
> > 
> > How about this sort of thing instead ...
> > 
> >       -- The algorithm only needs the last two digits of the year
> >       -- so we remove the 'century' part, if any, of the supplied year.
> > >     while pYear > 100 do
> > >         pYear -= 100
> > >     end while
> > BTW, we could have done this in one line ...
> > 
> >       pYear = remainder(pYear, 100)
> > 
> > 
> > >     -- add 1/4 to the year
> > Again, I can read the code and you have accurately described what it is
> > doing, but why is it doing this?
> > 
> > >     pYear += floor( pYear / 4 )
> > > 
> > >     -- determine month code, MONTH_CODE
> > >     -- is declared else where in our code
> > Why? And how is it declared elsewhere? 
> > 
> > >     lCode = MONTH_CODE[ pMonth ]
> > > 
> > >     -- add the values
> > Duh! Yes, that's what the code does, but why?
> > 
> > >     lResult = pYear + lCode + pDay
> >  
> > >     -- get remainder of seven and add 1
> > Again this is an accurate description of what the code is doing. But I
> > don't have a clue why? How would I know if this code is right or not?
> > Why '7'? Why add one?
> > 
> >       -- Having calulated the number of days we now divide this into
> >       -- weeks and the left over amount is the offset into a week. We
> >       -- add one to convert the offset into an index, which is then
> >       -- returned to the caller. 
> > >     lResult = remainder( lResult, 7 ) + 1
> > > 
> > >     return lResult
> > > end function



Here's my version of the same thing, probably not documented so well but very
accurate. For the whole thing see my 'moredates' in the archives.

1 the remaining DAYS in this month

2 the remaining days in the remaining months of this year 3 the middle years

4 the days in months of the last year 5 the days in the last month global function get_day(sequence mydate)returns a weekday in the future sequence today,unknown integer totdays,a totdays=find(getday(),DAY) today=parse_date(getdate()) unknown=parse_date(mydate) if getdec(today[3]) > getdec(unknown[3]) then puts(1,mydate&" has passed") elsif getdec(today[3]) < getdec(unknown[3]) then --------------[1] deal with the remaining DAYS of this month-- adj_days_in_month(today[3]) totdays=totdays+DAYS_IN_MONTH[getdec(today[2])]-getdec(today[1]) --------------[2] deal with rest of this year MONTHS---------- adj_days_in_month(today[3]) for x=getdec(today[2])+1 to 12 dodeal with rest of this year totdays=totdays+DAYS_IN_MONTH[x] end for

---

[3] deal with the middle YEARS (if nescessary)------ for x = getdec(today[3])+1 to getdec(unknown[3])-1 dodeal with middle years a=find(sprintf("%02d",x),LEAPYEAR) if a then totdays=totdays+366 else totdays=totdays+365 end if end for --------------[4] deal with the last months 0f the last year---- adj_days_in_month(unknown[3]) for x=1 to getdec(unknown[2]) -1 dodeal with the months of the last year totdays=totdays+DAYS_IN_MONTH[x] end for

---

[5] deal with the last days of the last month-- totdays=totdays+getdec(unknown[1])

---

elsif getdec(today[3]) = getdec(unknown[3]) then if getdec(today[2]) > getdec(unknown[2]) then puts(1,mydate&" has passed") abort(0) elsif getdec(today[2]) < getdec(unknown[2]) then -------------- deal with the remaining DAYS of this month-- adj_days_in_month(today[3]) totdays=totdays+DAYS_IN_MONTH[getdec(today[2])]-getdec(today[1]) --------------deal with the months------- for x=getdec(today[2])+1 to getdec(unknown[2])-1 do totdays=totdays+DAYS_IN_MONTH[x] end for -------------- deal with the last days of the last month-- totdays=totdays+getdec(unknown[1]) elsif getdec(today[2]) = getdec(unknown[2]) then ------------ deal with the remaining DAYS of this month-- totdays=totdays+getdec(unknown[1])-getdec(today[1]) end if end if while totdays>700 do totdays=totdays-700 end while while totdays>70 do totdays=totdays-70 end while while totdays>7 do totdays=totdays-7 end while return LONGDAY[totdays] end function

don cole SF }}}