OpenEuphoria

Re: Document A Project

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

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