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