3 \documentclass[12pt,a4]{article}
6 \bibliographystyle{alpha}
8 \def\sisac{{\footnotesize${\cal I}\mkern-2mu{\cal S}\mkern-5mu{\cal AC}$}}
9 \def\isac{${\cal I}\mkern-2mu{\cal S}\mkern-5mu{\cal AC}$}
10 \def\isa{${\cal I}\mkern-2mu{\cal S}\mkern-5mu{\cal A}$}
11 \def\see{$\rightarrow$}
13 \title{The Rules of the \isac{} - Developers}
14 \author{The \sisac-Team\\
15 {\tt isac@ist.tugraz.at}\\
16 Institute for Softwaretechnology\\
17 University of Technology,
19 % Institut f\"ur Softwaretechnologie\\
20 % Technische Universit\"at Graz}
28 \begin{center}\begin{minipage}{13.0cm}\footnotesize
30 \end{minipage}\end{center}
33 This document contains {\em all} rules agreed upon by the members of the \sisac-team. The wide range of these rules will supposedly lead to a split into several documents in the future.
37 \section{The \isac{} charta}\label{charta}
38 \sisac{} is dedicated to learning as an essence of human beeing. On the one hand learning is concerned with {\em individual growth}, with reflection about the part of human thinking which can be mechanized my mathematics, with gaining insight into foundations of our technology oriented society --- issues \sisac{} wants to contribute with a novel kind of math tutoring software. On the other hand, learning is a {\em social activity} in various ways: it concerns cooperation between the learner and some kind of teacher, between teachers and media producers, between educational administrators and course designers --- issues \sisac{} wants to contribute with a novel kind of math authoring software. And last not least the \sisac-project is a learning community itself, embedded into the {\em development in science} as a collective kind of learning.
40 In the future, an advisory board shall be engaged to balance these issues. Presently the \sisac-project is primarily engaged into software development, and for this part the rules are set up first below.
43 \item {\bf \sisac{}} is an academic open-source project on learning mathematics.
44 \item {\bf The charta determines}\label{determines} the administrative rules (pt.\ref{changes}.), the rights and obligations of the members of the (pt.\ref{team}.) \sisac-team with respect to the development process and the (pt.\ref{products}.) products resulting from this process within the \sisac-project.
46 \item {\bf Changes of the rules}\label{changes} of the charta are set up to acceptance of two thirds of the (pt.\ref{active}.) active members of the \sisac-team in a (pt.\ref{meeting}.) \sisac-meeting. Proposals for changes have to be made public one week ahead of a decision in {\tt isac@ist.tugraz.at}. In case of parity of votes the (pt.\ref{admin}.) \sisac-admin decides.
48 \item {\bf The \sisac-products are common property}\label{products} of the members of the (pt.\ref{team}.) \sisac-team, where each person holds the copyright on the code he or she is author of. The \sisac-products comprise the \sisac{} mathematics kernel, the \sisac{} tutoring system, the \sisac{} authoring system the \sisac{} web-reader and \sisac{} content.
50 Detailed rules for cases of re-engineering will be established in time these cases will come up.
52 \item {\bf \sisac{} is an open source project}\label{open} under GNU public license; the \sisac-project follows the idea, that educational software should be free for everyone involved in learning and teaching.
54 However, if \sisac-content, probably developed outside the \sisac-project, is commercially used, \sisac{} will ensure fair sharing of profit with the \sisac-team. A procedere for such cases will be established in time these cases will come up.
56 \item {\bf A certain sub-task}\label{subtask} of the \sisac-project is defined between an aspirant and the \sisac-admin (usually by agreement on certain JUnit tests) following the checklist \ref{check-assign}. Ninety percent of this task are covered by this initial agreement; ten percent may be required for tasks from the todo-list (pt.\ref{todolist}.) urgently needed for accomplishing general goals of the \sisac-project.
58 By the agreement on the sub-task the aspirant becomes an active member (pt.\ref{active}.) of the \sisac-team (pt.\ref{team}.).
60 \item {\bf The responsibility for parts of code}\label{responsibility} is given at the agreement on the sub-task (pt.\ref{subtask}). The responsibility is fixed for a list of directories, where the member is allowed to create new files (and subdirectories in agreement with the (pt.\ref{admin}.) \sisac-admin) and/or a list for already existing files.
62 If the request for changes in the code concerns files of {\em one} other active member, then the change is due to the agreement between the two members. If the change concerns more than one collegue, the agreement is up to involve the \sisac-admin, usually at a (pt.\ref{day}.) team-day. The \sisac-admin is responsible for all code not in responsibility of an active member of the \sisac-team.
64 \item {\bf The cvs repository} contains code with all tests running (in SML as well as JUnit-tests in Java). In order to sustain this state, these steps must be followed:
66 \item Merge new code with the repository by {\tt update}.
67 \item If there are conflicts, clarify them with the owner of the respective file (see pt.\ref{responsibility}).
68 \item Run {\em all} tests (either in SML or in Java; in case of changes in the Java-SML interface both).
69 \item If some tests do not run, contact the owner of the respective testcase (see pt.\ref{responsibility}).
70 \item If there are no more conflicts and all tests are running, {\tt commit} the new code.
71 \item The {\tt commit} has to be accompanied with a comment of one or two lines. If the new code is related to discussions in an \sisac-meeting, the comment has to reference the respective protocol (pt.\ref{protocol}).
72 \item Renamed files and directories must be commitet with a comment containing 'oldname->newname' in order to make the history tracable.
74 When formulating the comments in commits remember: {\em what} has been changed is implied by the changes (and these are recorded by cvs automatically), usually it is more informative {\em why} something had be updated, or at which occasion some new code has bee added.
76 \item {\bf The \sisac-team comprises}\label{team} all persons who ever have obtained a task (pt.\ref{subtask}.) from the (pt.\ref{admin}.) \sisac-admin {\em and} who have received admission from two thirds of the (pt.\ref{active}.) active members in an (pt.\ref{meeting}.) \sisac-meeting.
78 \item {\bf The active members}\label{active} of \sisac-team are those who have not yet left the active development process, usually on completion of their thesis or written report. The membership can be abandoned like any other rule (pt.\ref{changes}). An active member is discharged from this sub-task (pt.\ref{subtask}) due to a procedure described in sect.\ref{final-handover}.
80 \item {\bf The \sisac-admin}\label{admin} is the member of the \sisac-team supervising the whole development process and the adherence to the rules. %The \sisac-admin is elected by the \sisac-team for 1 semester in an (pt.\ref{meeting}.) \sisac-meeting according on how rules are changed (see above).
82 He prosecutes breach of the rules by assigning a task, adequate to the annoyance caused in the team, from the todo-list (pt.\ref{todolist}) to the malefactor.
84 In case of absence the \sisac-admin has to determine a representative. In case of permanent unavailability the \sisac-meeting has to determine a new \sisac-admin.
86 \item {\bf An \sisac-meeting}\label{meeting} requires the presence of two thirds of the members of the \sisac-team, the \sisac-admin and the announcement like a rule (see above). The task of the \sisac-meeting is to change rules of this charta including the active membership.
88 \item {\bf A team-day}\label{day} obliges each active member of the \sisac-team to be present one certain day a week. This day is fixed at the beginning of a semester once for a semester.
90 %AK041016 "eventual" bzw. "eventually" heißt "in endeffekt, letztendlich, schließlich", keinesfalls heißt es "eventuell" ... WN schon ausgebessert, danke !
91 The team-day serves discussing interfaces and other topics of common interest, personal concerns of the members of the \sisac-team, pair programming and \sisac-meetings if required. A topic of common interest should be published in {\tt isac@ist.tugraz.at} at least 3 days ahead.
93 \item {\bf A protocol}\label{protocol} is written for each \sisac-meeting and for points of common interest at a team-day. It serves the information of active members, who could not take part in the \sisac-meeting and for later lookup. Thus the protocol briefly describes the points of discussion and certainly contains all decisions.
95 The protocol is written by the active members of the \sisac-team all around in alphabetical order. It is stored in the cvs {\tt isac/admin}, thus allowing for comments.
97 \item {\bf A todo-list}\label{todolist} contains tasks outside the sub-tasks defined according to pt.\ref{subtask}. Entries in the list are accepted by the \sisac-admin or by affirmation of two thirds in an \sisac-meeting.
99 Tasks on this list are assigned to members of the \sisac-team by the \sisac-admin for urgent reasons w.r.t. general \sisac{} goals or for prosecution of breach of rules.
104 \section{Testdriven development}\label{testdriven}
105 \sisac{} is a research and development projekt; as such it has to deal with open research questions and changing requirements. Together with the middle size of the \sisac-team this gives the major prerequisites for a development process following the ideas of `extreme programming' \cite{extreme-1}.
107 %AK041016 ich glaube, dass isac phasenweise ein RESEARCH project ist. das funktioniert ganz gut, an ideen und experimenten hat es nie gemangelt. phasenweise ist isac aber ein PRODUCTION project, zB wenn eines tages ein prototyp fertig sein soll, am ende gar zu einem bestimmten termin mit bestimmter funktionalität. das haut überhaupt nicht hin. in dieser phase sehe ich die wesentlichsten defizite. wenn man produzieren will, muss man sagen können, was man haben will und bis wann man das haben will. ausserdem müssen die notwendigen mittel dafür zur verfügung stehen und ressourcen und arbeit koordiniert werden, sonst keine production und kein product. bisher habe ich im text wenig hinweise darauf gefunden, wo ziele und deadlines herkommen, wie die ressourcen verteilt werden, wie die verteilung sichergestellt und überprüft wird und wie konflikte (zB um ressourcen oder prioritäten) gelöst werden.
109 In particular, all sub-tasks of development are defined by means of functional tests together with the \sisac-admin.
111 \subsection{Testdriven development in Java}\label{javatests}
112 Here are the rules for the part of development involving Java.
115 \item The subdirectories of {\tt src/java-tests} are kept an exact sub-tree of {\tt src/java}. Sub-tree means, that these subdirectories in {\tt src/java-tests/*} are omitted (w.r.t. {\tt src/java/*}) which are not needed for holding testcases and/or testsuites.
117 There are two exception to this rule:\label{dir-test-sub-dir-obj}
119 \item {\tt src/java-tests/isac/functest} see (\ref{functest}.) below
120 \item {\tt src/java-tests/isac/sml} contains checks of the XML-output of the SML-kernel.
123 \item Each testcase resides in {\em that} subdirectory of {\tt src/java-tests}, where the tested class resides in the respective subdirectory of {\tt src/java}. (Thus, below we do not distinguish between `subdirectories of {\tt src/java-tests/*}' and `subdirectories of {\tt src/java/*}'). Thus we can name both {\tt src/java/isac/*} and {\tt src/java-tests/isac/*} for short {\tt ISAC/*}. \label{dir-test--dir-obj}
125 \item A testsuite for class {\tt Yyy.java} is named {\tt TestYyy.java}, and the testcases for a method {\tt Yyy.xxx} in {\tt TestYyy.java} are named {\tt testXxx*}. \label{test-naming} Mock-objects are named {\tt MockXxx} where {\tt Xxx} is the name of an existing class.
127 \item If a testcase refers to methods of several objects, then it resides on the common rootdirectory of the objects' directories. This root is {\tt src/java-tests/isac} ultimately. TODO what if there will be too many testcases~? \label{dir-test--dir-objects}
129 \item {\em All} testcases and testsuites in a directory {\tt ISAC/*/aaa/} are called by a specific testsuite {\tt /ISAC/*/aaa/Testall.java}, and if there are subdirectories {\tt ISAC/*/aaa/?}, this specific testsuite calls the testsuites {\tt ISAC/*/aaa/?/Testall.java} (and does {\em not} go {\em several} levels deeper in the file hierarchy). Thus {\tt ISAC/*/aaa/Testall.java} contains {\em exactly} one additional call to {\tt ISAC/*/aaa/?/Testall.java} per immediate subdirectory {\tt ISAC/*/aaa/?/}. \label{dir-test leveldn 1}
131 \item The testsuite {\tt ISAC/Testall.java} is the root of the calling hierarchy and calls all existent {\tt ISAC/*/Testall.java} cascading down all tests, according to (\ref{dir-test leveldn 1}.), one {\tt Testall.java} per level.
133 \item Thus the implementor of a testcase for class {\tt ISAC.*.aaa.Yyy} is responsible that
135 \item the testcase is {\tt ISAC.*.aaa.TestYyy.java} according to (\ref{dir-test--dir-obj}.) and (\ref{test-naming}.).
137 \item This amounts to either
139 \item the directory {\tt src/java-tests/isac/*/aaa/} does already exist. Then the implementor has to
141 \item insert a call of his {\tt TestYyy.java} into {\tt src.java-tests.isac.*.aaa.Testall.java} (i.e.\ short {\tt ISAC.*.aaa.Testall.java})
143 \item or directory {\tt src/java-tests/isac/*/aaa/Testall.java} does {\em not} exist. Then the implementor has to
145 \item create directory {\tt src/java-tests/isac/*/aaa/}
146 \item create a testsuite {\tt ISAC.*.aaa.Testall.java} calling {\tt ISAC.*.aaa.TestYyy.java}
147 \item add a call of {\tt ISAC.*.aaa.Testall.java} to {\tt ISAC.*.Testall.java}, which has been brought to existence applying (\ref{dir-test leveldn 1}.) recursively.
159 \item Functional tests are kept in {\tt ISAC/functest}. \label{functest} They relate to the use-cases in the isac-docu.tex. In order to allow cross-referencing, the whole \LaTeX-label must be used in the code, e.g. {\tt $\backslash$label\{SPECIFY:check\}} (the numbering is useless due to ongoing changes to isac-docu.tex).
161 \item Each functional test is a separate JUnit-test. Thus it can be referenced within javadoc by {\tt @see}, as can be referenced JUnit-tests themselves.
163 \item Interlinking of unit-tests (with the javadoc {\tt @see}) is desirable.
165 \item One obvious and thus {\em mandatory} way originates from the proceeding in testdriven development:\\
166 Development starts with functional tests, usually followed by JUnit-tests covering parts of the function: these JUnit-tests must be interlinked bidirectionally with the respective functional test. (i.e.\ a JUnit-test should point at least at one functional test.
167 \item If a JUnit-test (`parent`) covers several other JUnit-tests (`children`), then this relation should be documented by bidirectional links between parent and children.
171 \item TODO get experience, if the tests are fast enought be run parallel to module-development; then consider how to separate them appropriately.
177 \subsection{Log4j and Chainsaw}
179 Debuggers (in particular the one implemented in Eclipse) have troubles with \sisac's modules running in different (virtual) machines --- stepping through the code gets stuck in javaRMI.
181 Thus we use Log4j and Chainsaw for debugging across modules. \sisac{} uses Chainsaw's priority levels as proposed at {\tt www.vipan.com/htdocs/log4jhelp.html}: Log4j by default can log messages with five priority levels.
183 \item Use debug to write debugging messages which should not be printed when the application is in production.
184 \item Info: \sisac{} uses this mode for presenting a survey on the communication between the modules.
185 \item Use warn for warning messages which are logged to some log but the application is able to carry on without a problem.
186 \item Use error for application error messages which are also logged to some log but, still, the application can hobble along. Such as when some administrator-supplied configuration parameter is incorrect and you fall back to using some hard-coded default value.
187 \item Use fatal for critical messages, after logging of which the application quits abnormally.
189 All levels highter than {\tt debug} are in the responsibility of the \sisac-admin. Thus casual overriding the usage above must be repaired by the \sisac-member on completion of his sub-task.
191 \noindent The logger must be declared as
193 private static final Logger logger = Logger.getLogger(....class.getName());
196 \noindent Each call must be guarded by the {\tt if} as in
198 if (logger.isDebugEnabled())
202 At level {\tt info} the following abbrevations are used:
204 {\def\arraystretch{1.1}
208 \begin{tabular}{ r | l | l}
209 abbrevation & module/class & comment \\ \hline
211 WA & WindowApplication & \\
212 BF & BrowserFrame & \\
213 WS & Worksheet & \\ \hline
214 & & modules between gui and mathengine \\
215 SM & SessionManager & ? unify with SE ?\\
216 SE & Session & ? unify with SM ?\\
217 UM & UserManager & ? remove ?\\
218 DG & DialogGuide & superordinate concept of BD, WD -- remove ?\\
219 BD & BrowserDialog & \\
220 WD & WorksheetDialog & \\ \hline
225 \caption{Abbrevations for survey on modules in the logger}
229 The messages concerning SM\dots DG are indented 2 spaces, the BR is indented 4 spaces, WA\dots is not indented.
232 \subsection{Testdriven development in SML}
235 \section{The coding standards}
237 \subsection{Task tags}
238 The following task tags are used for both, for Java and for SML.
242 {\tt FIX*ME} tags locations in the code where some {\em existing functionality} is established by a short-cut or a hack.
244 \item {\tt FIXME} has low priority, i.e. the fix need not made during the sub-task (see pt.\ref{subtask} of the \sisac-charta).
245 \item {\tt FIXXME} has normal priority, i.e. the fix should be made during the sub-task.
246 \item {\tt FIXXXME} has high priority, i.e. the fix should be made as soon as possible.
248 {\tt FIXME}s need to be discussed at the final hand-over (see the checklist \ref{final-handover}).
251 {\tt TO*DO} tags locations in the code where some {\em functionality is missing}.
253 \item {\tt TODO} has low priority, e.g. it is used by eclipse's code generator; the latter should be removed as soon as possible.
254 \item {\tt TOODO} has normal priority, i.e. the fix should be made during the sub-task.
255 \item {\tt TOOODO} has high priority, i.e. the fix should be made as soon as possible.
257 {\tt TODO}s need to be discussed at the final hand-over (see the checklist \ref{final-handover}).
259 If an author of a {\tt FIX*ME} or a {\tt TO*DO} sets the tag outside his part of responsibility to code (see pt.\ref{responsibility} of the \sisac-charta), he has to follow the coding standards pt.\ref{short-sign} on p.\pageref{short-sign}.
261 \subsection{Name tags}\label{nametags}
262 Name tags serve {\em short} comments, see the coding standards, eg. pt.\ref{short-sign} on p.\pageref{short-sign} or \ref{bad-hack} on p.\pageref{bad-hack}.
263 The name tags of the members of the \sisac-team are so far \dots
265 \begin{tabular}{ l | l | l }
266 name tag & username & name \\ \hline
267 AG & agriesma & Andreas Griesmayer \\
268 AK & akremp & Alan Krempler \\
269 CR & croppos? & Christian Ropposch \\
270 GK & gkompach & Georg Kompacher \\
271 GS & gschroet?& G\"unther Schr\"ottner \\
272 LK & akirchst & Alois Kirchsteiger \\
273 JL & jloinig & Johannes Loinig \\
274 MG & mgold & Matthias Goldgruber \\
275 MH & mhochrei & Mario Hochreiter \\
276 MK & mkoschuc & Manuel Koschuch \\
277 ML & mlang & Martin Lang \\
278 NC & nsimic & Nebojsa Simic \\
279 RG & rgradisc & Richard Gradischnegg \\
280 RK & rkoenig & Robert K\"onighofer \\
281 RL & rlang & Richard Lang \\
282 SK & & Stefan Karnel \\
283 TF & tfink & Thomas Fink \\
284 TO & tober & Thomas Oberhuber \\
285 WK & wkandl & Wolfgang Kandlbauer \\
286 WN & wneuper & Walther Neuper \\
290 The username is used by the cvs versioning system.
292 \subsection{Coding standards for Java}\label{standard-java}
293 The following closely resembles the `Dinopolis Java Coding Convention'.
296 \item The language for code is English. This applies for all names and identifers in the code as well as for all comments.
297 %\item The principles of simplicity, intuitivity and uniformity as described in section 1 should be followed.
298 \item Avoid the use of block comments (/* ... */) in the source code and use the line comments (//...) instead. This makes the source code less fragile to erroreneous deletions of code-lines and robust against the use of eclipses code-formatter. Eclipses code-formatter also badly handles //-comments if they are at the end of a long line; such comments should be {\em above} the respective line.
299 \item If it is absolutely necessary to put comments in the code to describe algorithmic details %(see also section 1.2)
300 preceed the according code fragment with a comment block rather than spreading the comments across the code fragment.
301 \item If it is absolutely necessary to clarify non-obvious code write short comments at the end of the appropriate code line. Nevertheless whenever such a comment seems necessary think twice if there is a better obvious solution that doesn't need a comment!
302 \item\label{short-sign} In exceptional cases (e.g.\ if the author is not an active member of the \sisac-team anymore) a comment may be added to a piece of code by someone who is {\em not} the author. In this case the comment has to be marked with {\tt NNyymmdd}, where {\tt NN} follows the table in sect.\ref{nametags}.
303 \item When describing a design pattern the name of the book which deals with this pattern should be cited (e.g.\ [Gamma et al. 1998]).
304 \item When describing algorithms the names of the book which deals with these algorithms and datastructures should be cited (e.g.[Sedgewick 1992].
305 \item The source code for every class (even for non-public classes) should reside in a file of its own. The only exception to this rule are inner classes and anonymous classes as it is per definition impossible to put them in files of their own.
308 * @author <author>, member of the ISAC-team,
309 * Copyright (c) ${year} by <author>
310 * created ${date} ${time}
311 * Institute for Softwaretechnology, Graz University of Technology, Austria.
313 * Use is subject to PGPL license terms.
317 \item When writing stand-alone programs the class with the {\tt main} method in it should not have anything to do with the functional part of the code. The same applies for applets: The {\tt Applet} class should not have anything to do with the functional part of the code.
318 \item Every class should be a member of a package. Classes belonging to the default package are undesired, even for testing.
319 \item Java import statements should be written in the following order:
321 \item Java Core API classes.
322 \item Java Extension API classes.
323 \item Classes from third party APIs.
324 \item \sisac{} classes.
326 To increase the readability of the import part, all imports should be sorted by package names, that means imported classes belonging to the same package can be found in consecutive lines. Between the three categories mentioned above a single blank line is recommended. Using wildcards in import statements makes updating of classes hard and should therefore be avoided.
327 \item Classes should be preceded by a Javadoc header of the following form \footnote{Adapt eclipse: $<$Window$><$Preferences$><$Java$><$Code Style$><$Code Templates$>$ accordingly~!}:
330 * Description of the class in HTML format, if a useful link can
331 * be given in the running text do this with
332 * @link fully.qualified.Class#method(fully.qualified.Param)}
333 * @author <authorname>
334 * @version <version number>
335 * @see <fully.qualified.Classname#methodName(param-classes)>
336 * @deprecated <if applicable write reason here, otherwise omit
344 \item Prefix methods by a Javadoc header of the following form, if the method is {\em not} given by an interface:
347 * Description of the method in HTML format, if a link can
348 * be given in the running text do this with {@link
349 * fully.qualified.Classname#methodName(fully.qualified.Paramclass)}
350 * @param <paramname> <paramdescription>
351 * @return <return value>
352 * @exception <exception> <description when it is thrown>
353 * @see <fully.qualified.Classname#methodName(param-classes)>
354 * @deprecated <reason if applicable, otherwise omit this line>
356 public Object myFunction(Object test_param) throws MySpecialException {
360 If the method is given by an interface, the description shall {\em not} repeat the related description in the interface; use {\tt @see} and refine the related description if necessary.
363 \item \label{bad-hack} If bad hacks are absolutely unavoidable for whatever reason (e.g.\ absolutely have to meet a deadline, etc..) they should be tagged by a hack-start and hack-end comment of the following form, {\tt NNyymmdd} according to coding standard no.\ref{short-sign}:
365 // FIXXME.NNyymmdd hack: <description of the hack>
367 [..... the hack .....]
371 For {\tt($<$author, date$>$)} the signature described in \ref{short-sign} has to be used.
373 To facilitate a grep, the keyword FIXXME should be written in upper-case and with at least two `X's. More than two are allowed and should be used for really bad hacks - as a rule of thumb: the more `X's the word FIXXME contains the worse the hack is, up to a maximum of five `X's \footnote{Adapt eclipse: $<$Project$>$Properties$<$Java Task Tags$>$ accordingly !}. All hacks that have found their way into the code should be removed as soon as possible!
375 \item Name identifiers according to the following naming conventions \footnote{Adapt eclipse: $<$Window$><$Preferences$><$Java$><$Code Style$><$Code Templates$>$ accordingly~!}:
381 \> {\em I} FollowedByName \\
383 \> AllWordsCapitalizedWithoutUnderscores \\
385 \> firstWordLowerCaseRestCapitalizedWithoutUnderscores \\
386 {\bf Constants} (= finals): \\
387 \> ALL\_UPPER\_CASE\_WITH\_UNDERSCORES \\
388 {\bf Class and instance member variables}: \\
389 %AK041016 if you write "with trailing underscores" don't forget the trailing underscore_ ... WN danke !
390 \> all\_lower\_case\_with\_underscores\_and\_with\_trailing\_underscore\_ \\
391 {\bf Auto variables} (=variables used locally in methods): \\
392 \> all\_lower\_case\_with\_underscores \\
394 \> ClassNameEndsWithException
397 Besides these general naming rules some special naming conventions apply: All methods which change properties of classes should be named {\tt setXXX}. The methods returning the value of certain properties of classes can be divided into two categories: {\tt getXXX} for non-boolean properties and {\tt isXXX} for boolean values respectively. Example:
399 public void setCounter(int value) {
402 public int getCounter() {
405 public void setReadOnly(boolean value) {
408 public boolean isReadOnly() {
413 \item The following code structuring conventions apply \footnote{Adapt eclipse: $<$Window$><$Preferences$><$Java$><$Code Style$><$Code Formatter$>$ accordingly~!}:
415 \item Write opening curly braces at the end of the preceding code.
416 \item Write closing curly braces around code-blocks in lines of their own.
417 \item Indent code-blocks by two spaces. Don't use tabs for indentations but use spaces instead. Only indent the code block, not the curly braces!
418 \item When invoking methods the opening brace always should follow the method name without any whitespaces.
419 \item Use the eclipse formatter each time you commit a source file.
422 \item \label{java-doc-2} java-doc is generated separately for the production-code in {\tt java} and for the test-cases in {\tt java-tests}. Thus {\em do NOT reference from java to java-tests} --- this kind of reference is implicitly documented by the naming convention which mirrors directories, files, classnames, methodnames etc., see sect.\ref{javatests}.
426 \subsection{Coding standards for SML}\label{standard-sml}
427 The following closely resembles the standards given in \cite{Paulson:91}.\\
430 \section{\isac{} documents}
431 \sisac{} as an academic project relies on the motivation, the expertise and the dedication of the members of the \sisac-team. Thus the documents are kept to an absolute minimum.
432 \subsection{Survey on the documents}\label{survey-docs}
433 \paragraph{All the documents} maintained in the \sisac-project are presently:
434 \subparagraph{The \sisac{} documentation} of the system has the purpose to ease entering a new sub-task. Each member of the \sisac-team is challenged to contribute to the documentation within his or her sub-task to furtherly ease the entering of follow-up sub-tasks.
435 \subparagraph{The \sisac-charta} contains {\em all} rules agreed upon by the members of the \sisac-team; see sect.\ref{charta} in this document.
436 \subparagraph{The \sisac-diary} gives an account on the activities going on across the different groups (development of the front-end, of the mathematics engine, of math content, etc.) in the project .
437 \subparagraph{The todo-list} contains tasks outside the sub-tasks defined; see the \sisac-charta pt.\ref{todolist}. Each project sometimes needs awful things to be done ;-( in order to succeed.
438 \subparagraph{The protocols} are written for each \sisac-meeting and for points of common interest at a team-day (finally phase 2 convinced the team of the necessity of this document ;-); see the \sisac-charta pt.\ref{protocol}.
439 \subparagraph{Add-ons to the protocols} may contain more voluminous comments on discussions, details of design considerations etc. than acceptable in the protocol. This add-on must have the same date in the filename as the protocol it is added on.
440 \subparagraph{The work-plans} are set up separately for each sub-task. There was no need for a formalized work-plan or a project plan over several sub-tasks so far.
441 \subparagraph{The final reports} conclude each sub-task, beeing it a seminar/project or practical part of some kind of thesis; see sect.\ref{final-reps}. They are source of major updates of the \sisac{} documentation (preferably by copy and past), and thus follow the same standards, see sect.\ref{standard-docs}
442 \subparagraph{The work-reports} contain information important for continuing work related to a specific sub-task, if such information cannot becovered by {\tt TO*DO}s and {\tt FIX*ME}s in the code.
445 \paragraph{Administrative details on the documents:} Most of the documents require versioning, thus they are located in the cvs-repository at {\tt /isac/admin} and sub-directories included in the field 'name' of the table below.
448 \begin{tabular}{ l | l | l | l | l | l | l}
449 document & occasion & author & dispatch & audience & standard & name \\\hline
450 documen- & sub-task finished & act.mem & \sisac-admin
451 & public & documents & {\tt ../doc/}\\
452 \hspace{0.2cm}-tation & & & & & &\hspace{0.2cm}{\tt isac-docu.tex}\\
453 & & & & & &{\tt ../doc/}\\
454 & & & & & &\hspace{0.2cm}{\tt math-eng.tex}\\
455 \sisac-charta & start phase 3 & \sisac-admin & \sisac-admin
456 & public & documents & {\tt isac-rules.tex}\\
457 \sisac-diary & completion of & act.mem. & act.mem.
458 & act.mem.s & template & {\tt diary/}\\
459 & UCs, phases etc.& & & & &\hspace{0.2cm}{\tt yymm-mm.txt}\\
460 & meetings, & & & & & {\tt }\\
461 & changes in team,& & & & & {\tt }\\
462 & presentations & & & & & {\tt }\\
463 todo-list & start phase 3 & \sisac-admin & \sisac-admin
464 & act.mem.s & template & {\tt TODO-list.txt} \\
465 protocol & meeting, & act.mem. & \sisac-admin
466 & act.mem.s & template & {\tt protocols/}\\
467 & & & & & &\hspace{0.2cm}{\tt yymmdd.txt} \\
468 add-on & meeting, & act.mem. & act.mem.
469 & act.mem.s & none & {\tt protocols/} \\
470 & team-day & & & & &\hspace{0.2cm}{\tt yymmdd-addon.txt}\\
471 work-plan & start sub-task & new mem. & \sisac-admin
472 & act.mem.s & template & {\tt projplans/NN.txt}\\
473 final report & sub-task & mem. & \sisac-admin
474 & act.mem.s & documents & {\tt ../doc/NN/}\\
475 & & & supervisor & & & {\tt da-username.tex}\\
476 work-report & sub-task finished & mem & mem.
477 & act.mem.s & template & {\tt workreports/NN.*}\\
478 responsibility & & & & & & {\tt code-}\\
479 for code & & \sisac-admin & \sisac-admin
480 & act.mem.s & & {\tt -responsibility.txt}\\
481 % & & & & & & {\tt }\\
485 A 'member' of the \sisac-team is abbreviated by 'mem' above. Templates are held in the respective directoy with the name {\tt template.*} or given by the initial entry in the respective document.
488 \subsection{Standards for the documentation}\label{standard-docs}
489 These standards hold for the \sisac{} design documents, i.e. the user requirements and the software requirements document, the architectural design and software design document, the use cases and test cases, and the final reports, see see sect.\ref{final-reps} below.
491 These documents are written in \LaTeX, which is unfamiliar with many authors; thus the standard is kept to a minimum of sophistication. The aim is to provide for easy merging (parts of) the final reports into the \sisac-docu \cite{isac:all}.
493 \subparagraph{The structure} into parts, chapters, sections is given by the \sisac-documentation. The structure of the final reports should take the same levels.
495 \subparagraph{Definitions} are already given in the file {\tt isac-docu.tex} (the definitions will be extracted into a separated file {\tt preample.tex} as soon as some details with separate compilation are solved,see '\LaTeX ing' on p.\pageref{latexing} below). In order to avoid conflicts, they {\em must all} be copied into the separate reports at the very beginning of writing~!
497 \subparagraph{Logos} i.e. \sisac{} and \isac{} are fairly primitive \LaTeX-constructs. Both require a \{\} for separating the subsequent word; \sisac{} (fixed size~!) is for use within paragraphs, \isac{} for headlines.
499 \subparagraph{User-requirements, software-requirements and use-cases} have all their respective defintions by {\tt $\backslash$newcommand} and {\tt $\backslash$newtheorem} in {\tt preamble.tex}; they {\em must} be used. How to use, just look into the isac-docu.tex files~! See also 'labels' below.
500 \footnote{\cite{AK04:thesis} proposed more elegant definitions for them, which shall be introduced in the future.}
503 \subparagraph{Labels and files-names} must be headed by the name tag of the author, see sect.\ref{nametags} on p.\pageref{nametags} --- this is by no means an elegant way of avoiding conflicts when integrating the final reports into the isac-docu.tex files, but who knows a better one~?
505 Moreover, labels of user-requirements start with {\tt UR}, software-requirements start with {\tt UR} and use-cases start with {\tt UC}. Thus a typical label is {\tt $\backslash$label\{UR.WN-short-description\}} and the respective reference {\tt UR$.\backslash$ref\{UR.WN-short-description\}} --- note the preceding {\tt UR}.
507 Files-names {\em must not} contain underscores (\_) for the (rare) cases they have to be cited within \LaTeX{} (otherwise we would have to use math-mode).
509 \subparagraph{Figures} should be generated using %the tools found at {\tt http://www.gnome.org/projects/dia} or (MH only !!!)
510 {\tt xfig}. The source files should have the same name as the {\tt*.eps}-files generated for \LaTeX, and they both must be located in a sub-directory {\tt fig} of the root-directory of the respective report (as is with {\tt isac-docu.tex}); And these file names must start with a name tag and must not contain underscores according to 'labels and files-names' above.
512 \subparagraph{Diagrams} should be created with the tools from {\tt http://uml.sourceforge.net/index.php}. Umbrello is open-source and seems to become {\em the} up-coming tool for UML-modeling.
514 \subparagraph{Reader's marks} are used in the (rare) cases, where a member of the \sisac-team is authorized by the \sisac-admin to edit parts of the \sisac-documents directly. Then the \sisac-admin will use the following, well proven, reader's marks:
516 % legend to the reader's marks:
518 % [] the brackets enclose comments additional to,
519 % and not belonging to the text
521 % {} the braces enclose exact proposals for new text,
522 % which are embedded into comments.
524 % / marks a character to be deleted in the line _above_
526 % ^ points to a certain position in the line above,
527 % usually concerning a comment or an insertion
529 The same marks are used for comments of the \sisac-admin within the final reports, if desired.
531 \subparagraph{\LaTeX ing} of the \sisac-documentation is done with {\tt 'latex isac-docu'} and {\tt 'latex math-eng'}. And each of the documents {\em must} be compiled with the \LaTeX-system actually installed at IST --- this is an indispensible prerequisite for maintainance of the documentation.
533 \label{latexing}Each part of the \sisac-documentation can be \LaTeX ed separately, the User Requirements Document by {\tt 'latex urd'} etc. This is due to a mechanism based on the file {\tt common.tex} copied from \cite{diller:latex}.
535 \subparagraph{Bib-texing} of the \sisac-documentation is done with {\tt 'bibtex isac-docu'} and {\tt 'bibtex math-eng'}. The related bib-files are the files {\tt isac/doc/bib/isac.bib} and \\{\tt isac/doc/bib/from-theses} maintained by the \sisac-admin.
537 All \sisac-related publications are in {\tt isac/doc/bib/isac.bib} (otherwise urge the \sisac-admin~!), and {\tt $\backslash$cite\{xxx\}} must use the labels {\tt xxx} already given.
539 Bib-tex files must be located in a sub-directory {\tt bib} of the root-directory of the respective report (as is with {\tt isac-docu.tex}).
544 \subsection{Final reports}\label{final-reps}
545 Most of the members of the \sisac-team work on sub-projects in \sisac{} within their regular studies, comprising a `Diplomarbeit' (diploma thesis), a `Software-Projekt und Bakk.-Arbeit B', a `Seminar/Projekt', or a `Praxis-Semester'. The latter usually is continued into a diploma thesis, too. Thus most of the sub-tasks end up with a final written report.
547 In the sequel there are supporting aids and rules for these reports and theses.
550 \paragraph{Support for writing} the final reports is given in several ways, most of them contained in the versioning system, the CVS as checked out into {\tt isac/}. There are
552 \item a lot of documents and papers is avaiable on \sisac s webspace {\tt www.ist.tugraz.at/projects/isac/www/content/publications.html} via download. Members of the \sisac-team obtain these papers, including \LaTeX-sources, figures etc. from the CVS at {\tt isac/doc} or directly from the \sisac-admin
554 \item in particular, surveys on \sisac{}, introductions to \sisac{}, proposals on how to locate sub-projects within \sisac{} etc. directly from the \sisac-admin
556 \item stylesheets for the reports, including the definitions of \sisac, \isac etc. in the CVS at {\tt isac/doc}.
558 \item a bib-file in the CVS at {\tt isac/doc/bib} for easy generation of bibliographies. This file is maintained by the \sisac-admin. Further bib-files can be supplied by the \sisac-admin.
563 \paragraph{Coordination with the \sisac-documentation} is both, helpful for writing a report or thesis, and mandatory in order to keep the documentation up to date. The following rules guide the coordination.
566 \item {\em Terms used in the \sisac-project,} as contained in an appendix of the \sisac-documentation, provide for efficiency in internal communication and for uniformity and tracability in presentation to the outside world. Thus, in particular, these terms {\em must} be used in reports and in theses.
568 \item Writing access to the \sisac-documentation in the cvs at {\tt isac/doc} is exclusively with the \sisac-admin (who may delegate certain tasks).
570 \item The {\em Requirements Document}, both the user requirements and the software requirements in the \sisac-documentation, must provide justification for all design decisions in a report. If gaps in the requirements document become apparent, they have to be filled in coordination with the \sisac-admin.
572 \item The {\em Architectural Design Document} may overlap with design considerations in a report or thesis. Respective parts of the document may be copied into the report (and cited). And if there are changes or refinements in the design, the respective parts of the report will be copied into the document in cooperation with the \sisac-admin.
574 \item The {\em Software Design Document} usually will be refined, updated and completed by parts of a report; again, these parts of the report will be copied into the document in cooperation with the \sisac-admin.
576 \item The {\em Usecases} are shifted into the code as soon as they are implemented: the practical parts of the project/seminar or the thesis are defined by functional tests according to sect.\ref{testdriven}. Nevertheless, a usecase must be referenced by the full \LaTeX-label, e.g. {\tt $\backslash$label\{SPECIFY:check\}}.
578 TODO.WN050527 after decision for/against doxygen: %In the Usecases Document the related usecases are removed, only a reference to the respective functional test is kept in a survey on usecases.
579 %The same holds for the system views, which will be transferred into the test partitions in the code as soon as {\tt javadoc} will be replaced by {\tt doxygen}.
580 \item If a major part is copied from a final report to the \sisac-documentation, then such a part is marked within both, in the source (the report) and in the destination (the documentation), e.g.
582 %WN050518---AK04:thesis.p.67-76->isac-SDD------BEGIN don't remove line
583 %WN050518---AK04:thesis.p.67-76->isac-SDD------END don't remove line
589 The first two checklists concern the begin and the end of a sub-task.
591 \subsection{Checklist for assigning a sub-task}\label{check-assign}
592 This checklist concerns the adoption of a sub-task as defined in pt.\ref{subtask} on p.\pageref{subtask}.
594 \item the \sisac-admin presents the essence and the most important rules of the \sisac-charta \\{\tt www.ist.tugraz.at/projects/isac/publ/isac-rules.pdf}
596 agree on an individual access to the practice of the rules in the \sisac-charta
597 \item receive an account at the Institute for Softwaretechnology, IST (the \sisac/admin arranges an appointment with the IST-admin).
598 \item describe the sub-task: this usually is an interactive procedure within the team lasting for some time. Anyway, it shall be finalised within 3 weeks. The description depends on the specific sub-task and partially on the working style of the current \sisac-team. Usually the description comprises some of the following tasks:
599 \item relate the sub-task to existing use-cases
600 \item relate the sub-task to existing parts of the isac-docsu.tex, i.e. the actual version of \\{\tt www.ist.tugraz.at/projects/isac/publ/isac-docu.ps.gz}
602 \item assign the source-directories and files the new member is responsible for
603 \item fix an appointment for a work-plan describing appropriate milestones for the sub-task (should be within 4 weeks in general)
604 \item fix the type of documentation; this may be a thesis (see sect.\ref{final-reps}) or a work-report only (see sect.\ref{survey-docs}). The former is expected to be discussed with the \sisac-admin in order to ensure compatibility with the \sisac-documents; see sect.\ref{standard-docs} for standards.
605 \item mail a personal web-page for
606 \\{\tt www.ist.tugraz.at/projects/isac/www/content/team.html} (should be within 4 weeks in general); the \sisac-admin copies it into the webspace.
608 \item the \sisac-admin assigns a name tag to the new member (see the table in sect.\ref{nametags})
609 \item check if the administrative duties with the university are accomplished (enrolment for semin/project, for Bakk or Diploma thesis etc.
610 \item introduce the new member of the \sisac-team on a \sisac-meeting (pt.\ref{meeting} on p.\pageref{meeting})
611 \item introduce the new member to other members of the \sisac-team responsible for related sub-tasks.
613 \item hand-over the work-plan to the \sisac-admin (who approves and publishes it -- see sect.\ref{survey-docs})
614 \item (\sisac-admin: update the web-pages, publish work-plan, announce in the isac-diary.tex)
618 \subsection{Checklist for the final hand-over of a sub-task}\label{final-handover}
619 This checklist concerns the final hand-over of a sub-task usually releasing an active member (pt.\ref{active} on p.\pageref{active}).
621 \item check your code, i.e. the code you are responsible for (pt.\ref{responsibility} of the \sisac-charta)
625 \item the coding standards are met
626 \item no warnings / errors
627 \item remove all obsolete {\tt FIX*ME}s and {\tt TO*DO} (and oly these~!) and comment the others
628 \item all outcommented code must have an extra comment indicating the reason.
630 \item java-specific checks
632 \item the coding standards are met, in particular, all important classes and methods have a java-doc comment
633 \item java-doc compiles both, the {\tt java}-directory and the {\tt java-tests}-directory (separated following pt.\ref{java-doc-2} on p.\pageref{java-doc-2})
634 \item check your code via javadoc: each class and each method with a brief and relevant comment
635 \item remove all calls of the logger, except those with status 'fatal' which have (exclusively~!) been managed by the \sisac-admin.
636 \item reduce the number of {\tt System.out.println}'s to a reasonable amount of output, which might help (and not overwhelm) your successors in development.
639 \item sml-specific checks
644 \item check the usecases done or not done (and comment the latter in the (JUnit-) testcase~!)
645 \item finialize the documentation, i.e. the final report and/or the assigned parts of the isac-docu:
647 \item check w.r.t. the standards in sect.\ref{standard-docs}
648 \item actually latex the report on the IST-system (indispensible for reuse of the text and the figures~!) and generate a {\tt ps}-file by {\tt dvips da-NN.dvi -o}, as an option a {\tt pdf}-file additionally (which causes additional effort with the figures, in general).
649 \item hand over the sources to the \sisac-admin for publication and/or for integration into the \sisac-docu.
651 \item finish your work-plan to your sub-task, see sect.\ref{survey-docs}.
652 \item make an appointment with the \sisac-admin and discuss ...
655 \item specific points in your code
656 \item each {\tt FIX*ME} within your code
657 \item each {\tt TO*DO} in this code
659 \item the final-report
661 This meeting may take more than one appointment.
662 \item discuss the most important points from above at a team-day (pt.\ref{day} on p.\pageref{day}) or at an isac-meeting (pt.\ref{meeting} on p.\pageref{meeting}).
663 \item optionally deposit a final work-report (see sect.\ref{survey-docs}) on the sub-task, on experiences with the \sisac-team etc.
664 \item if you are also a member of TU Graz, ask the \sisac-admin to arrange an appointment for giving a presentation at an IST-meeting.
666 \item return the keys, books, cables etc. you have from the IST.
667 \item say goodbye at a team-day or at an \sisac-meeting.
671 \bibliography{bib/isac,bib/from-theses,bib/math-eng}