Re: Document A Project
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
|
Not Categorized, Please Help
|
|
