Shannon V. OKeets
Posts: 22095
Joined: 5/19/2005 From: Honolulu, Hawaii Status: offline
|
quote:
ORIGINAL: wfzimmerman Bugs seem to be one of the most significant and difficult to manage risk factors in the project. I remember that at the outset of the project some of us suggested creating a web-accessible bug tracking data base, but Matrix had security concerns and nothing happened. Our bug tracking database is still simply a list that Steve keeps, and this has always worried me. It has now been almost 2 years (IIRC) since the project started, things in the outside world and in Matrix's environment have changed, should we revisit this issue and see if Matrix can't implement a web-accessible bug tracking database? It seems pretty clear that tracking, solving, and closing bugs is going to be a key issue in determining whether the project meets its schedule and quality goals. The project is being managed and implemented so professionally in other respects, I hate to see us use a less than optimal method for quality assurance. For my own purposes, keeping track of things that aren't working or that I want to improve, is pretty straightforward and not a problem. Once I get the beta testers sending in dozens of reports for version 4.00, then having a program/system/package to manage them will be more of a concern. There are several difficulties with using simple lists: - gathering information on bugs so I can understand what the beta tester experienced - recreating the problem - accumulating information about the problem (different circumstances under which it occurs, fixes that have been tried and did/did not work, etc.) - providing feedback to the person who reported the problem on its status - combining/eliminating duplicate reports on the same/similar problem I will give this some more thought once I get version 4.0 out the door. Though debugging appears time consuming, a lot of that time is spent on: (1) figuring out how the program processes its response to player actions (2) documenting those lines of code and/or subsystems (3) clarifying the code by renaming variables, function, and procedures (4) improving the code through standardization, centralization, and/or decentralization. The first 2 happen almost all the time when I 'fix' a problem. 3 and 4 occur less frequently but require a lot more time. Here is some documentation I created last month. I see I didn't even mention this in the monthly report. All of the following documentation was created by me through examining the existing code and following call sequences and the use of different variables and functions throughout the program. When I started work on this last month (or perhaps 2 months ago) I had a blank sheet of paper. This falls into the category of #2 - documenting subsystems. When I write this stuff, it is so I can read it 6 months later when I am confused about how the subsystem works. I also find the call sequences very helpful when tracking down a problem (in this case, a problem related to the Moving Stack). ============ MovingStack Documentation (as of April 1, 2007) Introduction MovingStack is used primarily to hold the units the player is in the process of moving. Most often this is when the player is repositioning a unit or units already on the map. An important secondary use is to take units from the setup tray and place them on the map. The module MoveStack contains the routines for TMoveStack. However because TMoveStack is based on TStack, many of the routines MovingStack uses are in the module Stack. Definition, Initialization, and Memory Release MovingStack is defined in the module InProgressVar. It is initialized in the initialization portion of the module MoveStack and free’d in the finalization portion of the same module. The MovingStack starts empty when it is created. Adding Units There are 3 places in the code where units are added to MovingStack ∙ WIFUnits, EnterPool: This is the main routine for adding units to the MovingStack. It handles the updating of the unit’s location and the placement of the unit from one location to another, be that from the map or from an off map pool (e.g., the setup tray). ∙ MoveStack, TransferToMovingStack: This routine is used to return a unit from a temporary stack back to the MovingStack. At times, the program needs to place units in a stack that the player can manipulate. Once this secondary processing is completed, this routine is used to move the original units back into the MovingStack. ∙ Setup, PrepareMovingStack: This routine takes the units that the player has selected from the setup tray and places them in the moving stack so the player can then position them on the map. TransferToMovingStack is called by: ∙ SimControl, WIFNavalInterceptionChoice This handles the processing of the player’s decision whether to stop or fight his way through when intercepted during naval movement. ∙ WIFUSEntryAction, DoEntryAction DoDelayedEntryActions, WIFUSEntryAction, and EntryAction call DoEntryAction. The last two are the same, with one for Internet major powers and the other for the local major power. Some US entry actions are delayed until the US player is the phasing player (?). The units in MovingStack are temporarily transferred to USEntryStack while the player responds to US entry actions and then they are transferred back to MovingStack once the US entry action has been processed. For example, when the USSR occupies Eastern Poland, units in Eastern Poland are repositioned using the MovingStack. ∙ MoveStack, DeleteStack This routine takes the next stack of units in the NavalMovingStack table and transfers them into MovingStack. During naval movement, there might be several moving stacks active at the same time. For instance, the phasing player moves units that are intercepted at sea and he decides to fight through. As a result of combat, some naval units from both sides abort back to port. During the abort back to port, either side’s units might be intercepted, and so on. The program maintains a list of naval unit stacks that need to be moved. EnterPool is called by OffMapMove and MoveOffMap. Those routines, in turn, are only called by MoveIntoPool, which, with the argument upMoving, is only called by MoveInto. There are 3 places in the code where MoveInto is called: ∙ SimControl, WIFUnitCreateMove This routine is only used when splitting a convoy into separate units. Each of the new units is given the same location as the original convoy unit. That may be MovingStack (?). ∙ WIFUnits, MoveToStack This is called after loading the units in a saved game, to give them their correct Unit Placement. That may be MovingStack (?). ∙ WIFUnits, MoveToLoc This is the primary call to MoveInto. It is called by MoveToMovingStack, MoveToLocation, and MoveToLocationTop. Only the first is exclusively for placing units in the MovingStack. Here are the places where MoveToLocation is called: ∙ MapTable, CancelStackMove ∙ MoveStack, SetStackValues, SetLandMoveValues, AddHexes, AddDef ∙ Naval, CreateCarrierPlane ∙ Naval, SplitConvoy ∙ SimControl, WIFUnitLoad ∙ UnitMenuProcs, UnitMenuLoad Here are the places where MoveToLocationTop is called: ∙ MapTable, CancelStackMove ∙ SimControl, WIFUndo, pRailMovement (twice) ∙ SimControl, WIFUnitMove (primary routine for changing unit placement). Here are the places where MoveToMovingStack is called: ∙ Main, ARailMoveFactoryExecute This routine creates a temporary unit to represent the factory while it is on the move. The temporary unit is place in the MovingStack so the player can indicate to which map hex it is going. ∙ MoveStack, SetStackValues, SetLandMoveValues, AddHexes, AddDef I do not understand what this code is doing. ∙ MoveStack, TransferToMovingStack This routine restores units to the MovingStack from either the USEntryStack or TransferStack. ∙ MoveStack, MoveToMovingStack This is a recursive call to move all the units that are being transported by the unit originally specified as being moved to the MovingStack. ∙ PhaseControlProcs, PhaseAdvanceAfterCombat Here the MovingStack is used for moving units in the advance after combat phase. ∙ PhaseControlProcs, PhaseForcedRebase Here the MovingStack is used for moving units in the forced rebase phase. ∙ GameMapArea, AddToMovingStack Here the MovingStack is used for moving air units in the return to base phase (for both attacker and defender). ∙ GameMapArea, AddToMovingStack (4 occurrences) Here the MovingStack is used to place a newly created temporary carrier air unit (when not playing with carrier air units) and any other air unit during air mission subphases. It is also used during all other game phases. ∙ UnitMenuProcs, UnitMenuLoad (twice) Here the MovingStack is used when the player selects Load Unit from the unit menu. ∙ GameInProgress, SetPhase When units overrun other units, the overrunning units are placed in the MovingStack. The routine AddToMovingStack is called from: ∙ MouseCommands, GMAMouseDown (4 occurrences) The MovingStack acquires the units the player selected from the unit selection form. That form is displayed when the player presses Shift Left button click. The more common way to pick up units is a simple Left button click, which picks up the top unit and places it into the MovingStack (any units it is transporting are also placed in the MovingStack). In summary, when the player clicks on a hex containing one or more units, the top unit is transferred to the MovingStack with the following call sequence: 1 MouseCommands, GMAMouseDown 2 GameMapArea, AddToMovingStack 3 WIFUnits, MoveToMovingStack 4 WIFUnits, MoveToLoc 5 WIFUnits, MoveInto 6 WIFUnits, MoveIntoPool 7 WIFUnits, MoveOffMap 8 WIFUnits, EnterPool Almost the same call sequence is used when a player clicks on a unit in the setup tray. The first call is to Setup, PrepareMovvingStack, which then calls the 3rd step in the above list: WIFUnits, MoveToMovingStack. Removing Units and Clearing the Stack The MovingStack is cleared of all units in the following places in the code: ∙ GameControls, GameDestroy When the game is destroyed. ∙ MapTable, CancelStackMove When a stack move is cancelled, after all the units have been moved back to their starting locations. ∙ WIFUSEntryAction, DoEntryAction After transferring all the units in MovingStack to USEntryStack. ∙ SimControl, WIFNavalInterception Prior to transferring the first stack in NavalMovingStack to the MovingStack. ∙ SimControl, WIFTryLandMove After determining whether a land move was possible and prior to destroying a unit or units (caused by overrun?). To remove individual units from the MovingStack the routine MovingStack.DeleteIndexOf(U) is called. This happens in only two places: ∙ Main, FormKeyPress, DoDestroyPartisan This is for voluntarily destroying the top partisan unit in the MovingStack. ∙ WIFUnits, LeavePool With its companion routine, EnterPool, LeavePool handles almost all relocations of units to/from the MovingStack. LeavePool is called by MoveInto which was partially analyzed previously in this document. Picking up where that analysis left off, here are the places in the code where WIFUnitMove is called. ∙ MoveStack, MoveTo This moves all the units in the MovingStack into a hex. The vast majority of unit movement is processed using this routine. For example, all air unit moves go through MovingStack.MoveTo. ∙ WIFUnits, MoveTo This moves an individual unit into a hex. All the odd actions like breaking down and reforming units, selecting HQ for emergency supply go through this routine. ∙ SimControl, WIFTryLandMove This runs a check on whether a land move can be made. If the check is ok, then the land move is made. ∙ SimControl, WIFTryNavalMove This runs a check on whether a naval move can be made. If the check is ok, then the naval move is made. ∙ SimControl, WIFTryTRailMove This runs a check on whether a rail move can be made. If the check is ok, then the rail move is made. In summary, the units in the moving stack are removed from the MovingStack (and usually placed on the map) through the following call sequence: 1 MouseCommands, GMAMouseDown 2 MoveStack, MoveTo 3 SimControl, WIFUnitMove 4 WIFUnits, MoveToLocationTop 5 WIFUnits, MoveInto 6 WIFUnits, LeavePool
_____________________________
Steve Perfection is an elusive goal.
|