<br><font size=2 face="sans-serif">Justin has a good point, but even in
complicated cases, the code will tell us WHAT it does. The commentary is
needed, in all circumstances to tell us WHY it does what it does. It should
do it in a way that allows the reader to understand what else might have
been done and still satisfy the functional requirement. The code is the
implementation, the commentary should represent the design. So providing
commentary at a functional (rather than statement) level is often to be
preferred for this reason.</font>
<br>
<br><font size=2 face="sans-serif">Is anybody interested in composing a
formal specification of how a virtual world engine should behave? Such
a specification would not be OpenSim specific, but should reflect a formal
model of which OpenSim is one possible refinement. It's something that
virtual worlds appears to lack at present. If anyone knows of an existing
specification, I'd very much appreciate a pointer.</font>
<br><font size=2 face="sans-serif"><br>
Best regards<br>
Alan<br>
-------------------<br>
T.J. Watson Research Center, Hawthorne, NY<br>
1-914-784-7286<br>
alan_webb@us.ibm.com</font>
<br>
<br>
<br>
<table width=100%>
<tr valign=top>
<td><font size=1 color=#5f5f5f face="sans-serif">From:</font>
<td><font size=1 face="sans-serif">Justin Clark-Casey <jjustincc@googlemail.com></font>
<tr valign=top>
<td><font size=1 color=#5f5f5f face="sans-serif">To:</font>
<td><font size=1 face="sans-serif">opensim-dev@lists.berlios.de</font>
<tr valign=top>
<td><font size=1 color=#5f5f5f face="sans-serif">Date:</font>
<td><font size=1 face="sans-serif">11/17/2008 08:48 AM</font>
<tr valign=top>
<td><font size=1 color=#5f5f5f face="sans-serif">Subject:</font>
<td><font size=1 face="sans-serif">Re: [Opensim-dev] API documentation</font></table>
<br>
<hr noshade>
<br>
<br>
<br><tt><font size=2>Mike Mazur wrote:<br>
> Hi,<br>
> <br>
> On Sun, 16 Nov 2008 19:23:00 -0800 (PST)<br>
> Charles Krinke <cfk@pacbell.net> wrote:<br>
> <br>
>> Is there any<br>
>> reason why we cannot solicit small "comment type" patches
to add<br>
>> summaries for namespaces and classes that are currently blank
to help<br>
>> our documentation along?<br>
> <br>
> I can't think of a reason. Helping with documentation is a great way
to<br>
> contribute to an open source project. Becoming familiar with the<br>
> codebase by documenting and reading it can be a great way to become
a<br>
> developer.<br>
<br>
+1  As far as I'm concerned, such summary documentation patches for
classes and methods are most welcome.  Other inline <br>
comment patches are also good, though I think it's important not to go
overboard where the code can speak for itself. <br>
For example, an extreme case would be<br>
<br>
// Increment the number by one<br>
number++;<br>
<br>
-- <br>
justincc<br>
Justin Clark-Casey<br>
</font></tt><a href=http://justincc.wordpress.com/><tt><font size=2>http://justincc.wordpress.com</font></tt></a><tt><font size=2><br>
_______________________________________________<br>
Opensim-dev mailing list<br>
Opensim-dev@lists.berlios.de<br>
</font></tt><a href="https://lists.berlios.de/mailman/listinfo/opensim-dev"><tt><font size=2>https://lists.berlios.de/mailman/listinfo/opensim-dev</font></tt></a><tt><font size=2><br>
</font></tt>
<br>
<br>