Project Template

The following is a one-page basic software project template. The template gives an outline for a minimal structure for a generic software project. Each section of the template has a description. Sections can be added, removed, or altered as needed to fit the software being built.

Note to Reader

If you discover an issue with this repository or have a question, please feel free to open an issue. I've included templates for the following issues:

• 🐞 Spelling and Grammar
• 🤷 Clarity
• ❓ Question
• 🚀 Enhancement

Release Tagging

The repository adopts semantic versioning for version labels.

vMAJOR.MINOR.PATCH

Cite Me 📃

BibTeX and APA on the right sidebar of GitHub.

Citations

1. Pressman, R. S. (2015). Software engineering: A practitioner's approach (Eighth edition). McGraw-Hill Education.

License ⚖️

Materials for a Course on Teaching Undergraduate Research by Joseph Starr and Lori Adams is licensed under CC BY-NC-SA 4.0

Resources

Links 🔗

Some useful resources:

• Software engineering : a practitioner's approach by Roger Pressman
• diagrams.net
• mermaid.js
• plantUML
• Semantic versioning for version labels.
• Conventional Commits
• Architectural Decision Records
• Markdown Architectural Decision Records
• git book
• COLORS

---

Mermaid examples 🧜

Git Graph

mermaid gitGraph commit commit branch develop checkout develop commit commit checkout main merge develop commit commit

State Machine

mermaid flowchart TD A[Christmas] -->|Get money| B(Go shopping) B --> C{Let me think} C -->|One| D[Laptop] C -->|Two| E[iPhone] C -->|Three| F[fa:fa-car Car]

Class Diagram

mermaid classDiagram Animal <|-- Duck Animal <|-- Fish Animal <|-- Zebra Animal : +int age Animal : +String gender Animal: +isMammal() Animal: +mate() class Duck{ +String beakColor +swim() +quack() } class Fish{ -int sizeInFeet -canEat() } class Zebra{ +bool is_wild +run() }

Sequence Diagram

mermaid sequenceDiagram Alice->>+John: Hello John, how are you? Alice->>+John: John, can you hear me? John-->>-Alice: Hi Alice, I can hear you! John-->>-Alice: I feel great!

Use Case Diagram

```mermaid

flowchart LR subgraph Generation direction LR G1([Get job]) end subgraph Presentation direction LR PL2([Get specific item]) end

subgraph Job Handling
    direction LR
    JH1([Build job])
    JH2([Process job])
end
subgraph Database Handling
    direction LR
    DH3([Read record set])
end

client["Client fa:fa-user"]
time["Time fa:fa-user"]
time --> JH2
client --> G1 --> JH2
JH1 -. include .-> DH3
JH2 -. include .-> DH3
client --> PL2 -. include .-> DH3

```

---

---

---

---

PlantUML Example 🌱

Use Case Diagram

```plantuml @startuml left to right direction actor Guest as g package Professional { actor Chef as c actor "Food Critic" as fc } package Restaurant { usecase "Eat Food" as UC1 usecase "Pay for Food" as UC2 usecase "Drink" as UC3 usecase "Review" as UC4 } fc --> UC4 g --> UC1 g --> UC2 g --> UC3 @enduml

```

---

A One-Page Project Doc

One paragraph project description. This should describe the goal you're trying to accomplish.

Planning

License

Select a License for the project. Write a sentence why you selected the license. Copy the respective "LICENSE" file from GitHub into the root of the repo.

Tasks

Describe how work is partitioned and distributed.

Version control

Describe a version control strategy. Will you branch? Will you rebase? How many branches will you maintain? How will versions be labeled?

Project Structure

Describe the file/directory structure of the project

• No directory or file shall contain:' ' or a capital letter.
• Source: contains all source code for the project. Each unit in a unique directory
• Test: contains all the test code for the project.
  • test/unit_test: contains all the unit test code for the project. Each unit in a unique directory
  • test/integration_test: contains all the integration test code for the project. Each test in a unique directory.

Define a unit

What is a unit for this project? A function? A class? Something else?

Quality

Describe the quality goals for the project. Is this a prototype? Is this a product?

Unit testing

Describe the unit testing strategy for this project.

Integration testing

Describe the integration testing strategy for this project.

Requirements

Functional Requirements

Functional requirements for a simple project should be phrased as use cases. Example can be found in docs.

Note that mermaid doesn't support use case diagrams, you need to use another tool(draw.io, plantUML) until this issue is resolved.

Non-Functional Requirements

Non-functional requirements should be listed.

Ex:

• Needs to run on the cluster.
• Needs to run on windows.
• Can't spend money on tools.

Technologies

Languages/Frameworks

Describe what languages/Frameworks will be used in the project. Include links to the languages/Frameworks and setup instructions. Include the reasons you're picking the languages/Frameworks (it's absolutely fine to pick a language because you already know how to work with it).

Style Guide

Pick a style guide from the internet that includes a formatter, link that here and use it.

Tools

Describe tools (IDE, Debugger, build tools, test framework) you'll use in the project. At a minimum, this should include your version control tooling.

Design and Documentation

This is the most important section of the document. People discuss documentation as only well commented code. While well commented code is important, having diagrams and real English descriptions for what you're trying to do is much more important!

System

A block diagram for the entire system.

Units

A collection of units for the project.

Unit: Title

Description

Describe the point of the unit

Diagrams

Include some diagrammatic description of the unit. A class diagram? A sequence diagram? A state machine?

Unit test description

List of the unit tests for this unit.

$\cdot$

$\cdot$

$\cdot$

Unit n: Title

Description

Describe what this unit is trying to accomplish.

Diagrams

Include some diagrammatic description of the unit. A class diagram? A sequence diagram? A state machine?

Unit test description

List of the unit tests for this unit.

Integration tests

List of the integration tests for the system.