1 Overview

Both procedural and object-oriented code is split into multiple files.

• In C++ each compilation unit consists of a header-implementation file pair.

• In Java each class is usually found in a .java file with a corresponding name1 which is included in a larger package.

• In Rust each module is defined by a single .rs file which is included in a larger crate. (Rust will not be discussed in this lecture.)

Keep in mind that module refers to an organizational unit within a codebase. Any time that word module is used during this lecture… it refers to the unit of code, not a course module.

import sys

from __future__ import annotations

• C++ codebase
• Java codebase

Your focus should be on formalizing a point of reference. You do not need to set up (or be able to set up) a C++ or Java codebase from scratch.

If you are truly curious… the upcoming directory listings were produced with the Linux tree command.

The uml directory contains UML Class diagrams. A UML Class diagram shows the connections (associations) between classes. This is not a standard directory. The .puml file is markup that PlantUML turns into an svg image.

└── uml
    ├── tic-tac-toe.puml
    └── tic-tac-toe.svg

Example 2: PlantUML Markup

@startuml
skinparam classAttributeIconSize 0
hide empty members

class Board {
	+Board()
	+get3Cells(int cell1Id, int cell2Id, int cell3Id) : CellTriple
	+getCell(int id) : CellValue
	+isFull() : bool
	-theBoard : std::array<CellValue, 9>
	+CellTriple : using
	+display(std::ostream& outs) : void
	+setCell(int id, CellValue newValue) : void
}

class Game {
	+Game()
	+Game(Player& p1, Player& p2)
	-board : Board
	+getBoard() : Board&
	+getLoser() : Player&
	+getPlayer1() : Player&
	+getPlayer2() : Player&
	+getWinner() : Player&
	-player1 : Player&
	-player2 : Player&
	-winner : Player*
	-ref : Referee
	+endedWithStalemate() : bool
	+endedWithWin() : bool
	+isNotOver() : bool
	+isOver() : bool
	+playRound() : bool
	-roundTurn(Player& player) : bool
	-numMovesMade : int
}


class Game::Referee {
	+Referee()
	+Referee(const Board& b)
	-allThreeMatch(const Board::CellTriple& triple) : bool
	+selectedCellIsEmpty(int move) : bool
	-boardRef : const Board&
	-checkForDiagonalWin() : int
	-checkForHorizontalWin() : int
	-checkForVerticalWin() : int
	+checkForWin() : int
	-playerNumFromSymbol(char sym) : int
}


class Player {
	+Player()
	+Player(std::string n)
	+isComputer() : bool
	+{static} isGeneric(const Player& possibleCylon) : bool
	+isHuman() : bool
	+getSymbol() : char
	-symbol : char
	+nextMove() : int
	+{static} referenceCylon : const Player
	-{static} PROMPT_MSG : std::string
	+getName() : std::string
	-name : std::string
	+setName(std::string n) : void
	+setSymbol(char newSymbol) : void
}



@enduml

Example 3: PlantUML Class Diagram

Java projects tend to follow the Android project conventions. These projects tend to use Gradle or Maven.

A full discussion of Gradle and Maven will be left for a software engineering course, e.g., CS 350. However, if you are truly curious… feel free to take a look at my CS 350 Introduction to Gradle lectures.

Example 4: Java Codebase

├── build.gradle
├── config
│   └── checkstyle
│       └── checkstyle.xml
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
└── src
    ├── main
    │   └── java
    │       └── edu
    │           └── odu
    │               └── cs
    │                   └── cs330
    │                       └── examples
    │                           ├── Board.java
    │                           ├── Game.java
    │                           ├── KeyboardStrategy.java
    │                           ├── package-info.java
    │                           ├── Player.java
    │                           ├── PlayTicTacToe.java
    │                           ├── Referee.java
    │                           └── Strategy.java
    └── test
        └── java
            └── edu
                └── odu
                    └── cs
                        └── cs330
                            └── examples
                                ├── TestBoard.java
                                ├── TestGame.java
                                ├── TestPlayer.java
                                └── TestReferee.java

└── src
    ├── main
    │   └── java
    └── test
        └── java

If you have no already done so… open a copy of Module-09/Example-3-Python.

A Python codebase is more organized than a C++ codebase and less over-divided than a Java codebase.

Example 7: Python Codebase

├── examples
│   ├── board.py
│   ├── game.py
│   ├── __init__.py
│   ├── player.py
│   ├── referee.py
│   └── strategy.py
├── play_tictactoe.py
├── tests
    ├── examples
    │   ├── test_board.py
    │   ├── test_game.py
    │   ├── test_player.py
    │   └── test_referee.py
    └── __init__.py

Note that setup.py and the distutils module were officially deprecated with the Python 3.12 release. The focus of this lecture is on general project structure. Topics such as

• publishing a Python package to PyPy

• setting up tox or poetry

• writing pyproject.toml

are outside the scope of this discussion. Let us start with the top-level directories and files.

Example 8: Python Codebase - Top Level

├── examples
├── play_tictactoe.py
├── tests

You will notice three items:

• examples - this is our package. In practice… the name should be more descriptive than the word examples. For this project… tictactoe would be more apt.

• play_tictactoe.py - this is the file containing our driver logic (i.e., the top-level functions that use the code from our package).

• tests - this is a directory that contains a test for each module in our package.

4.1 Definitions

I imagine that you are saying to yourself something along the lines of…

Are module and package the same thing? What are they, exactly?

A couple definitions are definitely in order.

• module - a .py file containing code (e.g., functions, classes, or constants) that is imported into a larger program through one or more import statements.

• package - a collection of .py files that serve as modules that are collected into a larger directory.

├── tests
    ├── examples
    │   ├── test_board.py
    │   ├── test_game.py
    │   ├── test_player.py
    │   └── test_referee.py
    └── __init__.py

|
├── examples
│   ├── board.py
│   ├── game.py
│   ├── player.py
│   ├── referee.py
│   ├── strategy.py
│   └── __init__.py