Code Documentation - JohnVin/Battleship GitHub Wiki

John: Looked through the source code files to find ones that needed comments vs those that already had comments. Found that some files needed commenting. Some are in more need of commenting than others. The list in order of importance by work to be done is as follows:

  • GameResources.vb
  • Player.vb
  • GameController.vb
  • GameLogic.vb
  • GameState.vb
  • Ship.vb
  • UtilityFunctions.vb

#Existing Code Documentation

There is a vast amount of XML documentation available in each in .vb file that has been supplied, with the exception of one or two missing bits of documentation.

DeploymentController.vb

  • This file is well documented.
  • This file controls the players actions during the deployment phase.

DiscoveryController.vb

  • This file is well documented.
  • The battle phase is handled by the DiscoveryController.

EndingGameController.vb
Following routines need comments Work backward to stop line numbers from shifting too much.

  • (112) Private Sub PlayHitSequence
  • (122) Private Sub PlayMissSequence
  • The EndingGameController is responsible for managing the interactions at the end of a game.

GameController.vb

  • This file is well documented.
  • The GameController is responsible for controlling the game, managing user input, and displaying the current state of the game.

GameLogic.vb
Module GameLogic Needs Comments

  • This file acts as the main for the project. It's job is to load resources, draw the screen and handle user input.

GameResources.vb
Work backward to stop line numbers from shifting too much. Following routines need comments

  • (4) Public Module GameResources
  • (6) Private Sub LoadFonts
  • (13) Private Sub LoadImages
  • (39) Private Sub LoadSounds
  • (49) Private Sub LoadMusic
  • (142) Private Sub ShowLoadingScreen
  • (158) Private Sub PlaySwinGameIntro
  • (177) Private Sub ShowMessage
  • (192) Private Sub EndLoadingScreen
  • (206) Private Sub NewFont
  • (210) Private Sub NewImage
  • (214) Private Sub NewTransparentColorImage
  • (218) Private Sub NewTransparentColourImage DUPLCATE ROUTINE???
  • (222) Private Sub NewSound
  • (226) Private Sub NewMusic
  • (230) Private Sub FreeFonts
  • (237) Private Sub FreeImages
  • (244) Private Sub FreeSounds
  • (251) Private Sub FreeMusic
  • (258) Public Sub FreeResources
  • This file is responsible for loading fonts, images, sounds, music.

HighScoreController.vb

  • This file is well documented.
  • Controls displaying and collecting high score data.

MenuController.vb

  • This file is well documented.
  • The menu controller handles the drawing and user interactions from the menus in the game. These include the main menu, game menu and the settings menu.

UtilityFunctions.vb

  • This file lacks documentation for some public and private functions.
  • This file includes a number of utility methods for drawing and interaction with the mouse.

AI

AIHardPlayer.vb

  • This file has comprehensive documentation for all functions.
  • AIHardPlayer is a type of player. This AI will know directions of ships when it has found 2 ship titles and will try to destroy that ship. If that ship is not destroyed it will shoot the other way. Ship still not destroyed, then the AI knows it has hit multiple ships. Then will try to destroy all around tiles that have been hit.

AIMediumPlayer.vb

  • This file has comprehensive documentation for all functions.
  • The AIMediumPlayer is a type of AIPlayer where it will try and destroy a ship if it has found a ship.

AIOption.vb

  • This file has documentation for the enum it contains.
  • The file contains an enum for the different AI levels.

AIPlayer.vb

  • This file has comprehensive documentation for all functions.
  • The AIPlayer is a type of player. It can only deploy ships, it also has the functionality to generate coordinates and shoot at tiles.

AttackResult.vb

  • This file contains comprehensive documentation.
  • AttackResult gives the result after a shot has been made.

BattleShipsGame.vb

  • This file contains comprehensive documentation.
  • The BattleSHipsGame controls a big part of the game. It will add the two players to the game and make sure that both players ships are all deployed before starting the game. It also allows players to shoot and swap turns between players. It will also check if players are destroyed.

ISeaGrid.vb

  • This file contains comprehensive documentation.
  • The ISeaGrid defines the read only interface of a grid. This allows each player to see and attack their opponents grid.

Player.vb Work backward to stop line numbers from shifting too much. Following routines need comments

  • (84) Public ReadOnly Property IsDestroyed
  • (117) Public ReadOnly Property Hits
  • (134) Public ReadOnly Property Score
  • (201) Public Overridable Sub RandomizeDeployment
  • This file specifies that player has its own _PlayerGrid, and can see an _EnemyGrid, it can also check if all ships are deployed and if all ships are destroyed.

SeaGrid.vb

  • This file contains comprehensive documentation.
  • The SeaGrid is the grid upon which the ships are deployed. The grid is viewable via the ISeaGrid interface as a read only grid. This can be used in conjuncture with the SeaGridAdapter to mask the position of the ships.

SeaGridAdapter.vb

  • This file contains comprehensive documentation.
  • The SeaGridAdapter allows for the change in a sea grid view. Whenever a ship is presented it changes the view into a sea tile instead of a ship tile.

Ship.vb

  • This file contains comprehensive documentation.
  • A ship has all the details about itself. For example the shipname, size, number of hits taken and the location. It's able to add tiles, remove, hits taken and if its deployed and destroyed. Deployment information is supplied to allow ships to be drawn.

Enumerations

Tile.vb

  • This file contains comprehensive documentation.
  • Tile knows its location on the grid, if it is a ship and if it has been shot before.

ShipName.vb

  • This file contains comprehensive documentation for the enumeration.
  • An enumeration representing the names of all of the ships in the game.

TileView.vb

  • This file contains comprehensive documentation.
  • Tile view is an enumeration that represents the values that are visible for a given tile.

ResultOfAttack.vb

  • This file contains comprehensive documentation for the enumeration.
  • This is an enumeration that represents the result of an attack.

Direction.vb

  • This file contains comprehensive documentation for the enumeration.
  • This enumeration represents the direction the ship can be oriented.

GameState.vb

  • This file is well documented.
  • The Gamestates enumeration represents the state of the Battleships game play. This is used to control the actions and view displayed to the player.