1. Document A Project
- Posted by Andy <videogamefreak101 at hotmail.com> Feb 18, 2005
- 562 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 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
3. Re: Document A Project
- Posted by Andy <videogamefreak101 at hotmail.com> Feb 18, 2005
- 538 views
- Last edited Feb 19, 2005
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
5. 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? > 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, {})
7. Re: Document A Project
- Posted by Derek Parnell <ddparnell at bigpond.com> Feb 19, 2005
- 535 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
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
9. Re: Document A Project
- Posted by Greg Haberek <ghaberek at gmail.com> Feb 19, 2005
- 533 views
> 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
11. Re: Document A Project
- Posted by Tone Škoda <tskoda at email.si> Feb 19, 2005
- 533 views
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
13. Re: Document A Project
- Posted by Pete Lomax <petelomax at blueyonder.co.uk> Feb 20, 2005
- 553 views
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
don cole SF }}}