Re: Document A Project
- Posted by Derek Parnell <ddparnell at bigpond.com> Feb 19, 2005
- 536 views
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