[freehaven-cvs] Added section about documentation/specification for ...

[rabbi@seul.org]

Update of /home2/freehaven/cvsroot/doc/mixmaster-vs-reliable
In directory moria.mit.edu:/tmp/cvs-serv21880

Modified Files:
	mixvreliable.tex 
Log Message:
Added section about documentation/specification for Mixmaster and (lack 
thereof) for Reliable.


Index: mixvreliable.tex
===================================================================
RCS file: /home2/freehaven/cvsroot/doc/mixmaster-vs-reliable/mixvreliable.tex,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -d -r1.20 -r1.21
--- mixvreliable.tex	30 Jun 2004 22:29:31 -0000	1.20
+++ mixvreliable.tex	30 Jun 2004 23:22:21 -0000	1.21
@@ -692,6 +692,29 @@
 (There has been no known communication with the author of Reliable since
 February, 2000).}
 
+\subsection{Source code documentation}
+
+In order to facilitate source code review and verification of an
+application's correctness with regard to its implementation of a protocol,
+it is beneficial for both good commenting in the source code and a clear
+specification for its behaviour to exist. 
+
+Nearly no comments exist in the Reliable source code, and significant
+portions of its source code are difficult to understand due to the
+author's use of generic variable names and terse programming style.
+
+Comparatively, the source code for Mixmaster is at least partially
+commented, though major portions of the code do remain uncommented.
+Mixmaster's source files, functions, and variables use intuitive names,
+allowing a reader with a basic to intermediate knowledge of the C
+programming language to comprehend its behaviour, with some exceptions due
+to terseness in the code.
+
+While neither program is sufficiently commented or written clearly enough
+to allow a non-programer to easily learn how either system works, there
+exists a complete specification of the Mixmaster message format and
+Mixmaster node behavior~\cite{mixmaster-spec}. No such specification or
+description exists for Reliable.
 
 \subsection{Included libraries} 
 

***********************************************************************
To unsubscribe, send an e-mail to majordomo@seul.org with
unsubscribe freehaven-cvs       in the body. http://freehaven.net/