AISE1_CLASS/Clean Code exercise/example2_bank/bank_usecase.tex

\documentclass[12pt,a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[english]{babel}
\usepackage{geometry}
\geometry{margin=2.5cm}
\usepackage{xcolor}
\usepackage{tcolorbox}
\usepackage{booktabs}
\usepackage{hyperref}
\usepackage{listings}

\definecolor{seblue}{rgb}{0.0,0.28,0.67}
\definecolor{backcolour}{rgb}{0.95,0.95,0.92}

\lstdefinestyle{json}{
    backgroundcolor=\color{backcolour},
    basicstyle=\ttfamily\small,
    breaklines=true,
    showstringspaces=false,
    tabsize=2
}

\title{\textcolor{seblue}{Exercise 2: Bank Account Transaction Processor}\\[0.3em]
\large AISE501 -- AI in Software Engineering I}
\author{Dr.\ Florian Herzog}
\date{Spring Semester 2026}

\begin{document}
\maketitle

\section{Use Case}

A simple bank system maintains a set of customer accounts, each with a balance, currency, and status (\texttt{active} or \texttt{frozen}).
A series of transactions is submitted for processing.
The program must validate each transaction, apply valid ones, reject invalid ones, and produce output files recording the results.

\section{Input Files}

\subsection{Account State (\texttt{accounts.json})}

A JSON file containing an array of account objects:

\begin{lstlisting}[style=json]
{
  "accounts": [
    {
      "account_id": "ACC-001",
      "holder": "Alice Mueller",
      "balance": 5000.00,
      "currency": "CHF",
      "status": "active"
    },
    ...
  ]
}
\end{lstlisting}

\subsection{Transactions (\texttt{transactions.json})}

A JSON file containing an array of transaction objects.
Each transaction has a \texttt{type} (\texttt{deposit}, \texttt{withdrawal}, or \texttt{transfer}), an \texttt{account\_id}, an \texttt{amount}, and a \texttt{description}.
Transfers additionally have a \texttt{to\_account\_id}.

\section{Validation Rules}

A transaction is \textbf{rejected} if any of these conditions apply:

\begin{center}
\begin{tabular}{ll}
\toprule
\textbf{Condition} & \textbf{Applies to} \\
\midrule
Account ID does not exist                        & All types \\
Account status is not \texttt{active}            & All types \\
Amount is zero or negative                       & All types \\
Balance is less than withdrawal amount            & Withdrawal, Transfer \\
Target account does not exist                     & Transfer \\
Target account is not \texttt{active}             & Transfer \\
Unknown transaction type                          & -- \\
\bottomrule
\end{tabular}
\end{center}

\section{Output}

The program produces:

\begin{enumerate}
    \item \textbf{Console output} -- A summary of updated account balances, accepted transactions, and rejected transactions with reasons.
    \item \textbf{Updated account state} (\texttt{accounts\_updated.json}) -- The accounts JSON with balances modified by accepted transactions.
    \item \textbf{Transaction log} (\texttt{transaction\_log.json}) -- Two arrays: \texttt{accepted} and \texttt{rejected}, each transaction annotated with its \texttt{status} and (for rejections) a \texttt{reason}.
\end{enumerate}

\section{Expected Results}

Given the provided input files, the expected outcome is:

\begin{center}
\small
\begin{tabular}{lllp{5cm}}
\toprule
\textbf{TXN ID} & \textbf{Type} & \textbf{Result} & \textbf{Reason (if rejected)} \\
\midrule
TXN-001 & deposit    & Accepted & -- \\
TXN-002 & withdrawal & Accepted & -- \\
TXN-003 & withdrawal & Rejected & Insufficient funds \\
TXN-004 & deposit    & Rejected & Negative amount \\
TXN-005 & deposit    & Rejected & Account is frozen \\
TXN-006 & transfer   & Accepted & -- \\
TXN-007 & withdrawal & Rejected & Account not found \\
TXN-008 & deposit    & Rejected & Zero amount \\
\bottomrule
\end{tabular}
\end{center}

\section{Exercise}

Two implementations are provided:

\begin{enumerate}
    \item \textbf{\texttt{bank\_bad.py}} -- A working but poorly written version that violates many clean code and PEP\,8 principles.
    \item \textbf{\texttt{bank\_good.py}} -- A clean, well-structured version following PEP\,8 and clean code best practices.
\end{enumerate}

\subsection*{Tasks}

\begin{enumerate}
    \item Run both programs and verify they produce the same results.
    \item Read the bad version and list all clean code / PEP\,8 violations you can find.
    \item For each violation, explain which principle is broken and why it makes the code harder to read or maintain.
    \item Compare your list with the good version to see how each issue was resolved.
\end{enumerate}

\subsection*{Violations to Look For}

\begin{itemize}
    \item Unused imports (\texttt{sys}, \texttt{os}, \texttt{copy}, \texttt{datetime})
    \item No docstrings or module documentation
    \item Single-letter and abbreviated variable names (\texttt{a}, \texttt{t}, \texttt{d}, \texttt{tp}, \texttt{tid})
    \item Multiple statements per line (semicolons)
    \item No whitespace around operators and after commas
    \item Manual file open/close instead of context managers (\texttt{with})
    \item One giant function doing all validation (violates Single Responsibility)
    \item Duplicated validation logic for deposit/transfer amount checks
    \item No constants for file paths
    \item Missing \texttt{if \_\_name\_\_ == "\_\_main\_\_"} guard
    \item Inconsistent error handling and status assignment
    \item Hard-to-follow control flow with nested \texttt{if}/\texttt{elif}/\texttt{continue}
\end{itemize}

\end{document}