Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • tranp30/cas741
  • liangb30/cas-741-boliang
  • pignierb/cas741
  • jimoha1/cas741
  • huoy8/cas741
  • grandhia/cas741
  • chenq84/cas741
  • yex33/cas741
  • xuey45/cas741
  • garcilau/cas-741-uriel-garcilazo-msa
  • schankuc2/cas741
  • ahmady3/cas741
  • saadh/cas741
  • singhk56/cas741
  • lin523/cas741
  • fangz58/cas741
  • ceranich/cas741
  • norouf1/cas741
  • mirzam48/cas741
  • djavahet/cas741
  • hossaa27/cas741
  • yiding_el/cas-741-upate-name
  • sayadia/cas741
  • elmasn2/cas741
  • cheemf8/cas741
  • cheny997/cas741
  • ma209/cas741
  • mousas26/cas741
  • liuy363/cas741
  • wongk124/cas741
  • dua11/cas741
  • zhoug28/cas741
  • courses/cas-741-tst
  • liy443/cas-741-fork-csv
  • sochania/cas741
  • liy443/cas-741-update-csv-old
  • mahdipoa/cas741
  • wangz892/cas741
  • wangn14/cas741
  • defourej/cas741
  • zhaox183/cas741
  • smiths/cas741
42 results
Show changes
Commits on Source (475)
Showing
with 2 additions and 1194 deletions
......@@ -22,6 +22,8 @@ cabal.config
*.nav
*.out
*.snm
*.fdb_latexmk
*.fls
*-nup.pdf
.DS_Store
.iTeXMac
......
dist
cabal-dev
*.o
*.hi
*.chi
*.chs.h
.virtualenv
.hsenv
.cabal-sandbox/
cabal.sandbox.config
cabal.config
*.aux
*.log
*.vrb
*.blg
*.bbl
*.DS_Store
*.synctex.gz
*.toc
*.lof
*.lot
*.nav
*.out
*.snm
*-nup.pdf
.DS_Store
.iTeXMac
*-2x2.pdf
*.pyc
html
latex
*.class
# Temporary Excel files
~$*
LICENSE Information
\ No newline at end of file
# Project Name
Developer(s) Name:
Date of project start:
This project is ...
The folders and files for this project are as follows:
docs - Documentation for the project
refs - Reference material used for the project, including papers
src - Source code
test - Test cases
## Core latex/pdflatex auxiliary files:
*.aux
*.lof
*.log
*.lot
*.fls
*.out
*.toc
*.fmt
*.fot
*.cb
*.cb2
.*.lb
## Intermediate documents:
*.dvi
*.xdv
*-converted-to.*
# these rules might exclude image files for figures etc.
# *.ps
# *.eps
# *.pdf
## Generated if empty string is given at "Please type another file name for output:"
.pdf
## Bibliography auxiliary files (bibtex/biblatex/biber):
*.bbl
*.bcf
*.blg
*-blx.aux
*-blx.bib
*.run.xml
## Build tool auxiliary files:
*.fdb_latexmk
*.synctex
*.synctex(busy)
*.synctex.gz
*.synctex.gz(busy)
*.pdfsync
## Auxiliary and intermediate files from other packages:
# algorithms
*.alg
*.loa
# achemso
acs-*.bib
# amsthm
*.thm
# beamer
*.nav
*.pre
*.snm
*.vrb
# changes
*.soc
# cprotect
*.cpt
# elsarticle (documentclass of Elsevier journals)
*.spl
# endnotes
*.ent
# fixme
*.lox
# feynmf/feynmp
*.mf
*.mp
*.t[1-9]
*.t[1-9][0-9]
*.tfm
#(r)(e)ledmac/(r)(e)ledpar
*.end
*.?end
*.[1-9]
*.[1-9][0-9]
*.[1-9][0-9][0-9]
*.[1-9]R
*.[1-9][0-9]R
*.[1-9][0-9][0-9]R
*.eledsec[1-9]
*.eledsec[1-9]R
*.eledsec[1-9][0-9]
*.eledsec[1-9][0-9]R
*.eledsec[1-9][0-9][0-9]
*.eledsec[1-9][0-9][0-9]R
# glossaries
*.acn
*.acr
*.glg
*.glo
*.gls
*.glsdefs
# gnuplottex
*-gnuplottex-*
# gregoriotex
*.gaux
*.gtex
# htlatex
*.4ct
*.4tc
*.idv
*.lg
*.trc
*.xref
# hyperref
*.brf
# knitr
*-concordance.tex
# TODO Comment the next line if you want to keep your tikz graphics files
*.tikz
*-tikzDictionary
# listings
*.lol
# makeidx
*.idx
*.ilg
*.ind
*.ist
# minitoc
*.maf
*.mlf
*.mlt
*.mtc[0-9]*
*.slf[0-9]*
*.slt[0-9]*
*.stc[0-9]*
# minted
_minted*
*.pyg
# morewrites
*.mw
# nomencl
*.nlg
*.nlo
*.nls
# pax
*.pax
# pdfpcnotes
*.pdfpc
# sagetex
*.sagetex.sage
*.sagetex.py
*.sagetex.scmd
# scrwfile
*.wrt
# sympy
*.sout
*.sympy
sympy-plots-for-*.tex/
# pdfcomment
*.upa
*.upb
# pythontex
*.pytxcode
pythontex-files-*/
# thmtools
*.loe
# TikZ & PGF
*.dpth
*.md5
*.auxlock
# todonotes
*.tdo
# easy-todo
*.lod
# xmpincl
*.xmpi
# xindy
*.xdy
# xypic precompiled matrices
*.xyc
# endfloat
*.ttt
*.fff
# Latexian
TSWLatexianTemp*
## Editors:
# WinEdt
*.bak
*.sav
# Texpad
.texpadtmp
# Kile
*.backup
# KBibTeX
*~[0-9]*
# auto folder when using emacs and auctex
./auto/*
*.el
# expex forward references with \gathertags
*-tags.tex
# standalone packages
*.sta
# generated if using elsarticle.cls
*.spl
# DS_Store
*.DS_Store
%% Comments
\usepackage{color}
\newif\ifcomments\commentstrue
\ifcomments
\newcommand{\authornote}[3]{\textcolor{#1}{[#3 ---#2]}}
\newcommand{\todo}[1]{\textcolor{red}{[TODO: #1]}}
\else
\newcommand{\authornote}[3]{}
\newcommand{\todo}[1]{}
\fi
\newcommand{\wss}[1]{\authornote{blue}{SS}{#1}}
\newcommand{\plt}[1]{\authornote{magenta}{TPLT}{#1}} %For explanation of the template
\newcommand{\an}[1]{\authornote{cyan}{Author}{#1}}
%% Common Parts
\newcommand{\progname}{ProgName} % PUT YOUR PROGRAM NAME HERE %Every program
% should have a name
File deleted
\documentclass[12pt]{article}
\usepackage{hyperref}
\hypersetup{colorlinks=true,
linkcolor=blue,
citecolor=blue,
filecolor=blue,
urlcolor=blue,
unicode=false}
\urlstyle{same}
\usepackage{enumitem,amssymb}
\newlist{todolist}{itemize}{2}
\setlist[todolist]{label=$\square$}
\usepackage{pifont}
\newcommand{\cmark}{\ding{51}}%
\newcommand{\xmark}{\ding{55}}%
\newcommand{\done}{\rlap{$\square$}{\raisebox{2pt}{\large\hspace{1pt}\cmark}}%
\hspace{-2.5pt}}
\newcommand{\wontfix}{\rlap{$\square$}{\large\hspace{1pt}\xmark}}
\begin{document}
\title{MG Checklist}
\author{Spencer Smith}
\date{\today}
\maketitle
% Show an item is done by \item[\done] Frame the problem
% Show an item will not be fixed by \item[\wontfix] profit
\begin{itemize}
\item Follows writing checklist (full checklist provided in a separate document)
\begin{todolist}
\item \LaTeX{} points
\item Structure
\item Spelling, grammar, attention to detail
\item Avoid low information content phrases
\item Writing style
\end{todolist}
\item Module Decomposition
\begin{todolist}
\item One module one secret (unless an explicit exception is made, with a good
reason) - all ``and''s should be checked.
\item The uses relation is a hierarchy.
\item Secrets are nouns (generally).
\item Traceability matrix between modules and requirements shows every
requirement is satisfied by at least on module
\item Traceability matrix between modules and requirements shows that every
module is used to satisfy at least one requirement
\item Traceability matrix between likely changes and modules shows a one to
one mapping, or, if this is not the case, explains the exceptions to this
rule.
\item Level 1 of the decomposition by secrets shows: Hardware-Hiding,
Behaviour-Hiding and Software Decision Hiding.
\item Behaviour-Hiding modules are related to the requirements
\item Software-Decision hiding modules are concepts that need to be
introduced, but are not detailed in the requirements
\item Each Software Decision Hiding module is used by at least one
Behaviour-Hiding Module (if this isn't the case, an explanation should be
provided)
\item Uses relation is not confused with a data flow chart
\end{todolist}
\item MG quality
\begin{todolist}
\item Follow template
\item Low coupling
\item Satisfies information hiding
\end{todolist}
\end{itemize}
\end{document}
File deleted
\documentclass[12pt, titlepage]{article}
\usepackage{fullpage}
\usepackage[round]{natbib}
\usepackage{multirow}
\usepackage{booktabs}
\usepackage{tabularx}
\usepackage{graphicx}
\usepackage{float}
\usepackage{hyperref}
\hypersetup{
colorlinks,
citecolor=blue,
filecolor=black,
linkcolor=red,
urlcolor=blue
}
\input{../../Comments}
\input{../../Common}
\newcounter{acnum}
\newcommand{\actheacnum}{AC\theacnum}
\newcommand{\acref}[1]{AC\ref{#1}}
\newcounter{ucnum}
\newcommand{\uctheucnum}{UC\theucnum}
\newcommand{\uref}[1]{UC\ref{#1}}
\newcounter{mnum}
\newcommand{\mthemnum}{M\themnum}
\newcommand{\mref}[1]{M\ref{#1}}
\begin{document}
\title{Module Guide for \progname{}}
\author{Author Name}
\date{\today}
\maketitle
\pagenumbering{roman}
\section{Revision History}
\begin{tabularx}{\textwidth}{p{3cm}p{2cm}X}
\toprule {\bf Date} & {\bf Version} & {\bf Notes}\\
\midrule
Date 1 & 1.0 & Notes\\
Date 2 & 1.1 & Notes\\
\bottomrule
\end{tabularx}
\newpage
\section{Reference Material}
This section records information for easy reference.
\subsection{Abbreviations and Acronyms}
\renewcommand{\arraystretch}{1.2}
\begin{tabular}{l l}
\toprule
\textbf{symbol} & \textbf{description}\\
\midrule
AC & Anticipated Change\\
DAG & Directed Acyclic Graph \\
M & Module \\
MG & Module Guide \\
OS & Operating System \\
R & Requirement\\
SC & Scientific Computing \\
SRS & Software Requirements Specification\\
\progname & Explanation of program name\\
UC & Unlikely Change \\
\wss{etc.} & \wss{...}\\
\bottomrule
\end{tabular}\\
\newpage
\tableofcontents
\listoftables
\listoffigures
\newpage
\pagenumbering{arabic}
\section{Introduction}
Decomposing a system into modules is a commonly accepted approach to developing
software. A module is a work assignment for a programmer or programming
team~\citep{ParnasEtAl1984}. We advocate a decomposition
based on the principle of information hiding~\citep{Parnas1972a}. This
principle supports design for change, because the ``secrets'' that each module
hides represent likely future changes. Design for change is valuable in SC,
where modifications are frequent, especially during initial development as the
solution space is explored.
Our design follows the rules layed out by \citet{ParnasEtAl1984}, as follows:
\begin{itemize}
\item System details that are likely to change independently should be the
secrets of separate modules.
\item Each data structure is implemented in only one module.
\item Any other program that requires information stored in a module's data
structures must obtain it by calling access programs belonging to that module.
\end{itemize}
After completing the first stage of the design, the Software Requirements
Specification (SRS), the Module Guide (MG) is developed~\citep{ParnasEtAl1984}. The MG
specifies the modular structure of the system and is intended to allow both
designers and maintainers to easily identify the parts of the software. The
potential readers of this document are as follows:
\begin{itemize}
\item New project members: This document can be a guide for a new project member
to easily understand the overall structure and quickly find the
relevant modules they are searching for.
\item Maintainers: The hierarchical structure of the module guide improves the
maintainers' understanding when they need to make changes to the system. It is
important for a maintainer to update the relevant sections of the document
after changes have been made.
\item Designers: Once the module guide has been written, it can be used to
check for consistency, feasibility and flexibility. Designers can verify the
system in various ways, such as consistency among modules, feasibility of the
decomposition, and flexibility of the design.
\end{itemize}
The rest of the document is organized as follows. Section
\ref{SecChange} lists the anticipated and unlikely changes of the software
requirements. Section \ref{SecMH} summarizes the module decomposition that
was constructed according to the likely changes. Section \ref{SecConnection}
specifies the connections between the software requirements and the
modules. Section \ref{SecMD} gives a detailed description of the
modules. Section \ref{SecTM} includes two traceability matrices. One checks
the completeness of the design against the requirements provided in the SRS. The
other shows the relation between anticipated changes and the modules. Section
\ref{SecUse} describes the use relation between modules.
\section{Anticipated and Unlikely Changes} \label{SecChange}
This section lists possible changes to the system. According to the likeliness
of the change, the possible changes are classified into two
categories. Anticipated changes are listed in Section \ref{SecAchange}, and
unlikely changes are listed in Section \ref{SecUchange}.
\subsection{Anticipated Changes} \label{SecAchange}
Anticipated changes are the source of the information that is to be hidden
inside the modules. Ideally, changing one of the anticipated changes will only
require changing the one module that hides the associated decision. The approach
adapted here is called design for
change.
\begin{description}
\item[\refstepcounter{acnum} \actheacnum \label{acHardware}:] The specific
hardware on which the software is running.
\item[\refstepcounter{acnum} \actheacnum \label{acInput}:] The format of the
initial input data.
\item ...
\end{description}
\subsection{Unlikely Changes} \label{SecUchange}
The module design should be as general as possible. However, a general system is
more complex. Sometimes this complexity is not necessary. Fixing some design
decisions at the system architecture stage can simplify the software design. If
these decision should later need to be changed, then many parts of the design
will potentially need to be modified. Hence, it is not intended that these
decisions will be changed.
\begin{description}
\item[\refstepcounter{ucnum} \uctheucnum \label{ucIO}:] Input/Output devices
(Input: File and/or Keyboard, Output: File, Memory, and/or Screen).
\item ...
\end{description}
\section{Module Hierarchy} \label{SecMH}
This section provides an overview of the module design. Modules are summarized
in a hierarchy decomposed by secrets in Table \ref{TblMH}. The modules listed
below, which are leaves in the hierarchy tree, are the modules that will
actually be implemented.
\begin{description}
\item [\refstepcounter{mnum} \mthemnum \label{mHH}:] Hardware-Hiding Module
\item ...
\end{description}
\begin{table}[h!]
\centering
\begin{tabular}{p{0.3\textwidth} p{0.6\textwidth}}
\toprule
\textbf{Level 1} & \textbf{Level 2}\\
\midrule
{Hardware-Hiding Module} & ~ \\
\midrule
\multirow{7}{0.3\textwidth}{Behaviour-Hiding Module} & ?\\
& ?\\
& ?\\
& ?\\
& ?\\
& ?\\
& ?\\
& ?\\
\midrule
\multirow{3}{0.3\textwidth}{Software Decision Module} & {?}\\
& ?\\
& ?\\
\bottomrule
\end{tabular}
\caption{Module Hierarchy}
\label{TblMH}
\end{table}
\section{Connection Between Requirements and Design} \label{SecConnection}
The design of the system is intended to satisfy the requirements developed in
the SRS. In this stage, the system is decomposed into modules. The connection
between requirements and modules is listed in Table \ref{TblRT}.
\wss{The intention of this section is to document decisions that are made
``between'' the requirements and the design. To satisfy some requirements,
design decisions need to be made. Rather than make these decisions implicit,
they are explicitly recorded here. For instance, if a program has security
requirements, a specific design decision may be made to satisfy those
requirements with a password. In scientific examples, the choice of algorithm
could potentially go here, if that is a decision that is exposed by the
interface.}
\section{Module Decomposition} \label{SecMD}
Modules are decomposed according to the principle of ``information hiding''
proposed by \citet{ParnasEtAl1984}. The \emph{Secrets} field in a module
decomposition is a brief statement of the design decision hidden by the
module. The \emph{Services} field specifies \emph{what} the module will do
without documenting \emph{how} to do it. For each module, a suggestion for the
implementing software is given under the \emph{Implemented By} title. If the
entry is \emph{OS}, this means that the module is provided by the operating
system or by standard programming language libraries. \emph{\progname{}} means the
module will be implemented by the \progname{} software.
Only the leaf modules in the hierarchy have to be implemented. If a dash
(\emph{--}) is shown, this means that the module is not a leaf and will not have
to be implemented.
\subsection{Hardware Hiding Modules (\mref{mHH})}
\begin{description}
\item[Secrets:]The data structure and algorithm used to implement the virtual
hardware.
\item[Services:]Serves as a virtual hardware used by the rest of the
system. This module provides the interface between the hardware and the
software. So, the system can use it to display outputs or to accept inputs.
\item[Implemented By:] OS
\end{description}
\subsection{Behaviour-Hiding Module}
\begin{description}
\item[Secrets:]The contents of the required behaviours.
\item[Services:]Includes programs that provide externally visible behaviour of
the system as specified in the software requirements specification (SRS)
documents. This module serves as a communication layer between the
hardware-hiding module and the software decision module. The programs in this
module will need to change if there are changes in the SRS.
\item[Implemented By:] --
\end{description}
\subsubsection{Input Format Module (\mref{mInput})}
\begin{description}
\item[Secrets:]The format and structure of the input data.
\item[Services:]Converts the input data into the data structure used by the
input parameters module.
\item[Implemented By:] [Your Program Name Here]
\end{description}
\subsubsection{Etc.}
\subsection{Software Decision Module}
\begin{description}
\item[Secrets:] The design decision based on mathematical theorems, physical
facts, or programming considerations. The secrets of this module are
\emph{not} described in the SRS.
\item[Services:] Includes data structure and algorithms used in the system that
do not provide direct interaction with the user.
% Changes in these modules are more likely to be motivated by a desire to
% improve performance than by externally imposed changes.
\item[Implemented By:] --
\end{description}
\subsubsection{Etc.}
\section{Traceability Matrix} \label{SecTM}
This section shows two traceability matrices: between the modules and the
requirements and between the modules and the anticipated changes.
% the table should use mref, the requirements should be named, use something
% like fref
\begin{table}[H]
\centering
\begin{tabular}{p{0.2\textwidth} p{0.6\textwidth}}
\toprule
\textbf{Req.} & \textbf{Modules}\\
\midrule
R1 & \mref{mHH}, \mref{mInput}, \mref{mParams}, \mref{mControl}\\
R2 & \mref{mInput}, \mref{mParams}\\
R3 & \mref{mVerify}\\
R4 & \mref{mOutput}, \mref{mControl}\\
R5 & \mref{mOutput}, \mref{mODEs}, \mref{mControl}, \mref{mSeqDS}, \mref{mSolver}, \mref{mPlot}\\
R6 & \mref{mOutput}, \mref{mODEs}, \mref{mControl}, \mref{mSeqDS}, \mref{mSolver}, \mref{mPlot}\\
R7 & \mref{mOutput}, \mref{mEnergy}, \mref{mControl}, \mref{mSeqDS}, \mref{mPlot}\\
R8 & \mref{mOutput}, \mref{mEnergy}, \mref{mControl}, \mref{mSeqDS}, \mref{mPlot}\\
R9 & \mref{mVerifyOut}\\
R10 & \mref{mOutput}, \mref{mODEs}, \mref{mControl}\\
R11 & \mref{mOutput}, \mref{mODEs}, \mref{mEnergy}, \mref{mControl}\\
\bottomrule
\end{tabular}
\caption{Trace Between Requirements and Modules}
\label{TblRT}
\end{table}
\begin{table}[H]
\centering
\begin{tabular}{p{0.2\textwidth} p{0.6\textwidth}}
\toprule
\textbf{AC} & \textbf{Modules}\\
\midrule
\acref{acHardware} & \mref{mHH}\\
\acref{acInput} & \mref{mInput}\\
\acref{acParams} & \mref{mParams}\\
\acref{acVerify} & \mref{mVerify}\\
\acref{acOutput} & \mref{mOutput}\\
\acref{acVerifyOut} & \mref{mVerifyOut}\\
\acref{acODEs} & \mref{mODEs}\\
\acref{acEnergy} & \mref{mEnergy}\\
\acref{acControl} & \mref{mControl}\\
\acref{acSeqDS} & \mref{mSeqDS}\\
\acref{acSolver} & \mref{mSolver}\\
\acref{acPlot} & \mref{mPlot}\\
\bottomrule
\end{tabular}
\caption{Trace Between Anticipated Changes and Modules}
\label{TblACT}
\end{table}
\section{Use Hierarchy Between Modules} \label{SecUse}
In this section, the uses hierarchy between modules is
provided. \citet{Parnas1978} said of two programs A and B that A {\em uses} B if
correct execution of B may be necessary for A to complete the task described in
its specification. That is, A {\em uses} B if there exist situations in which
the correct functioning of A depends upon the availability of a correct
implementation of B. Figure \ref{FigUH} illustrates the use relation between
the modules. It can be seen that the graph is a directed acyclic graph
(DAG). Each level of the hierarchy offers a testable and usable subset of the
system, and modules in the higher level of the hierarchy are essentially simpler
because they use modules from the lower levels.
\begin{figure}[H]
\centering
%\includegraphics[width=0.7\textwidth]{UsesHierarchy.png}
\caption{Use hierarchy among modules}
\label{FigUH}
\end{figure}
%\section*{References}
\bibliographystyle {plainnat}
\bibliography{../../../refs/References}
\end{document}
\ No newline at end of file
# Makefile
# From https://danielkaes.wordpress.com/2009/03/14/compiling-latex-documents-using-makefiles/
PROJECT=MG
TEX=pdflatex
BIBTEX=bibtex
BUILDTEX=$(TEX) $(PROJECT).tex
all:
$(BUILDTEX)
$(BIBTEX) $(PROJECT)
$(BUILDTEX)
$(BUILDTEX)
clean-all:
rm -f *.dvi *.log *.bak *.aux *.bbl *.blg *.idx *.ps *.eps *.pdf *.toc *.out *~
clean:
rm -f *.log *.bak *.aux *.bbl *.blg *.idx *.toc *.out *.lof *.lot *~
\ No newline at end of file
# Module Guide
The folders and files for the module guide.
File deleted
\documentclass[12pt]{article}
\usepackage{hyperref}
\hypersetup{colorlinks=true,
linkcolor=blue,
citecolor=blue,
filecolor=blue,
urlcolor=blue,
unicode=false}
\urlstyle{same}
\usepackage{enumitem,amssymb}
\newlist{todolist}{itemize}{2}
\setlist[todolist]{label=$\square$}
\usepackage{pifont}
\newcommand{\cmark}{\ding{51}}%
\newcommand{\xmark}{\ding{55}}%
\newcommand{\done}{\rlap{$\square$}{\raisebox{2pt}{\large\hspace{1pt}\cmark}}%
\hspace{-2.5pt}}
\newcommand{\wontfix}{\rlap{$\square$}{\large\hspace{1pt}\xmark}}
\begin{document}
\title{MIS Checklist}
\author{Spencer Smith}
\date{\today}
\maketitle
% Show an item is done by \item[\done] Frame the problem
% Show an item will not be fixed by \item[\wontfix] profit
\begin{itemize}
\item Follows writing checklist (full checklist provided in a separate document)
\begin{todolist}
\item \LaTeX{} points
\item Structure
\item Spelling, grammar, attention to detail
\item Avoid low information content phrases
\item Writing style
\end{todolist}
\item MIS Module Classifications
\begin{todolist}
\item Types that only hold data (records) are modelled as exported types. For
instance, the StdntAllocTypes module in A2:
\url{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/blob/master/Assignments/A2/A2.pdf})
\item Types that have data (state) and behaviour are modelled as ADTs. The
MIS should use the keyword \textbf{Template}. An example is the BoardT ADT
given at
\url{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/blob/master/Assignments/A3/A3Soln/A3P1_Spec.pdf}
\item Abstract objects are used when there is only one instance. There is
state and behaviour. This most
often comes up for ``global'' reader and writer modules. For instance, a
module that does logging. Abstract objects do NOT use the word Template in
the main header. An example is given in the SALst module of A2:
\url{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/blob/master/Assignments/A2/A2.pdf}
\item Library modules are used when there is only behaviour, no state. They
are defined as Modules, but State Variables and Environment Variable
fields say ``None.''
\item If the module's MIS can be parameterized by type, then the keyword
\textbf{Generic} is used. Generic modules are usually also Template
modules, but not necessarily. An example is given in the Generic Stack
Module (Stack(T)) given in A3:
\url{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/blob/master/Assignments/A3/A3Soln/A3P1_Spec.pdf}
\item Abstract objects will have some kind of initialization method
\item Abstract objects will have an assumptions that programmers will
initialize first, or a state variable that is set from False to True when
the Abstract object is initialized - this state variable then needs to be
checked for each access program call
\end{todolist}
\item MIS and Mathematical syntax
\begin{todolist}
\item Exported constants are ``hard-coded'' literal values, not variables.
Constants are values that are known at specification (and therefore compile)
time
\item Operations do not mix incorrect types. For instance, a character is not
added to an integer, an integer is not ``anded'' with a Boolean, etc.
\item Our modified Hoffmann and Strooper notation is used, or any new notation
is clearly defined.
\end{todolist}
\item MIS Semantics for each module
\begin{todolist}
\item Each access program does something - either an output, or a state
transition
\item Access programs either change the state of something, or have an output.
Only rarely should an access program do both (as it does for the constructor
in an ADT.)
\item If there is an entry in the state transition, then the state of
something changes. The state change might be the local state variables, the
state variables for another module, or an environment variable.
\item Outputs use $out := ...$
\item Exceptions use $exc := ...$
\item If the state invariant is satisfied before an access program call, it
will remain satisfied after the call
\item State invariant is initially satisfied
\item Local functions make the specification easier to read (there is no
requirement that the local functions will actually be implemented in code)
\item Modules that deal with files, the keyboard, or the screen, have
environment variables to represent these respective entitites
\end{todolist}
\item MIS Quality inspection for each module
\begin{todolist}
\item Consistent
\item Essential
\item General
\item Implementation independent
\item Minimal
\item High cohesion
\item Opaque (information hiding)
\end{todolist}
\item MIS Completeness
\begin{todolist}
\item All types introduced in the spec are defined somewhere
\item All modules in MG are in the MIS
\item All required sections of the template are present for all modules
\end{todolist}
\end{itemize}
\end{document}
File deleted
\documentclass[12pt, titlepage]{article}
\usepackage{amsmath, mathtools}
\usepackage[round]{natbib}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{graphicx}
\usepackage{colortbl}
\usepackage{xr}
\usepackage{hyperref}
\usepackage{longtable}
\usepackage{xfrac}
\usepackage{tabularx}
\usepackage{float}
\usepackage{siunitx}
\usepackage{booktabs}
\usepackage{multirow}
\usepackage[section]{placeins}
\usepackage{caption}
\usepackage{fullpage}
\hypersetup{
bookmarks=true, % show bookmarks bar?
colorlinks=true, % false: boxed links; true: colored links
linkcolor=red, % color of internal links (change box color with linkbordercolor)
citecolor=blue, % color of links to bibliography
filecolor=magenta, % color of file links
urlcolor=cyan % color of external links
}
\usepackage{array}
\externaldocument{../../SRS/SRS}
\input{../../Comments}
\input{../../Common}
\begin{document}
\title{Module Interface Specification for \progname{}}
\author{Author Name}
\date{\today}
\maketitle
\pagenumbering{roman}
\section{Revision History}
\begin{tabularx}{\textwidth}{p{3cm}p{2cm}X}
\toprule {\bf Date} & {\bf Version} & {\bf Notes}\\
\midrule
Date 1 & 1.0 & Notes\\
Date 2 & 1.1 & Notes\\
\bottomrule
\end{tabularx}
~\newpage
\section{Symbols, Abbreviations and Acronyms}
See SRS Documentation at \wss{give url}
\wss{Also add any additional symbols, abbreviations or acronyms}
\newpage
\tableofcontents
\newpage
\pagenumbering{arabic}
\section{Introduction}
The following document details the Module Interface Specifications for
\wss{Fill in your project name and description}
Complementary documents include the System Requirement Specifications
and Module Guide. The full documentation and implementation can be
found at \url{...}. \wss{provide the url for your repo}
\section{Notation}
\wss{You should describe your notation. You can use what is below as
a starting point.}
The structure of the MIS for modules comes from \citet{HoffmanAndStrooper1995},
with the addition that template modules have been adapted from
\cite{GhezziEtAl2003}. The mathematical notation comes from Chapter 3 of
\citet{HoffmanAndStrooper1995}. For instance, the symbol := is used for a
multiple assignment statement and conditional rules follow the form $(c_1
\Rightarrow r_1 | c_2 \Rightarrow r_2 | ... | c_n \Rightarrow r_n )$.
The following table summarizes the primitive data types used by \progname.
\begin{center}
\renewcommand{\arraystretch}{1.2}
\noindent
\begin{tabular}{l l p{7.5cm}}
\toprule
\textbf{Data Type} & \textbf{Notation} & \textbf{Description}\\
\midrule
character & char & a single symbol or digit\\
integer & $\mathbb{Z}$ & a number without a fractional component in (-$\infty$, $\infty$) \\
natural number & $\mathbb{N}$ & a number without a fractional component in [1, $\infty$) \\
real & $\mathbb{R}$ & any number in (-$\infty$, $\infty$)\\
\bottomrule
\end{tabular}
\end{center}
\noindent
The specification of \progname \ uses some derived data types: sequences, strings, and
tuples. Sequences are lists filled with elements of the same data type. Strings
are sequences of characters. Tuples contain a list of values, potentially of
different types. In addition, \progname \ uses functions, which
are defined by the data types of their inputs and outputs. Local functions are
described by giving their type signature followed by their specification.
\section{Module Decomposition}
The following table is taken directly from the Module Guide document for this project.
\begin{table}[h!]
\centering
\begin{tabular}{p{0.3\textwidth} p{0.6\textwidth}}
\toprule
\textbf{Level 1} & \textbf{Level 2}\\
\midrule
{Hardware-Hiding} & ~ \\
\midrule
\multirow{7}{0.3\textwidth}{Behaviour-Hiding} & Input Parameters\\
& Output Format\\
& Output Verification\\
& Temperature ODEs\\
& Energy Equations\\
& Control Module\\
& Specification Parameters Module\\
\midrule
\multirow{3}{0.3\textwidth}{Software Decision} & {Sequence Data Structure}\\
& ODE Solver\\
& Plotting\\
\bottomrule
\end{tabular}
\caption{Module Hierarchy}
\label{TblMH}
\end{table}
\newpage
~\newpage
\section{MIS of \wss{Module Name}} \label{Module} \wss{Use labels for
cross-referencing}
\wss{You can reference SRS labels, such as R\ref{R_Inputs}.}
\wss{It is also possible to use \LaTeX for hypperlinks to external documents.}
\subsection{Module}
\wss{Short name for the module}
\subsection{Uses}
\subsection{Syntax}
\subsubsection{Exported Constants}
\subsubsection{Exported Access Programs}
\begin{center}
\begin{tabular}{p{2cm} p{4cm} p{4cm} p{2cm}}
\hline
\textbf{Name} & \textbf{In} & \textbf{Out} & \textbf{Exceptions} \\
\hline
\wss{accessProg} & - & - & - \\
\hline
\end{tabular}
\end{center}
\subsection{Semantics}
\subsubsection{State Variables}
\wss{Not all modules will have state variables. State variables give the module
a memory.}
\subsubsection{Environment Variables}
\wss{This section is not necessary for all modules. Its purpose is to capture
when the module has external interaction with the environment, such as for a
device driver, screen interface, keyboard, file, etc.}
\subsubsection{Assumptions}
\wss{Try to minimize assumptions and anticipate programmer errors via
exceptions, but for practical purposes assumptions are sometimes appropriate.}
\subsubsection{Access Routine Semantics}
\noindent \wss{accessProg}():
\begin{itemize}
\item transition: \wss{if appropriate}
\item output: \wss{if appropriate}
\item exception: \wss{if appropriate}
\end{itemize}
\wss{A module without environment variables or state variables is unlikely to
have a state transition. In this case a state transition can only occur if
the module is changing the state of another module.}
\wss{Modules rarely have both a transition and an output. In most cases you
will have one or the other.}
\subsubsection{Local Functions}
\wss{As appropriate} \wss{These functions are for the purpose of specification.
They are not necessarily something that is going to be implemented
explicitly. Even if they are implemented, they are not exported; they only
have local scope.}
\newpage
\bibliographystyle {plainnat}
\bibliography {../../../refs/References}
\newpage
\section{Appendix} \label{Appendix}
\wss{Extra information if required}
\end{document}
\ No newline at end of file
# Makefile
# From https://danielkaes.wordpress.com/2009/03/14/compiling-latex-documents-using-makefiles/
PROJECT=MIS
TEX=pdflatex
BIBTEX=bibtex
BUILDTEX=$(TEX) $(PROJECT).tex
all:
$(BUILDTEX)
$(BIBTEX) $(PROJECT)
$(BUILDTEX)
$(BUILDTEX)
clean-all:
rm -f *.dvi *.log *.bak *.aux *.bbl *.blg *.idx *.ps *.eps *.pdf *.toc *.out *~
clean:
rm -f *.log *.bak *.aux *.bbl *.blg *.idx *.toc *.out *~
\ No newline at end of file
# Module Interface Specification #
Suggest following something like the example used in Lab 11 (Box 3D).
Use doxygen (or equivalent) to document the interface for your modules.
# Design Documentation
The folders and files for this folder are as follows:
Describe ...