Regarding one of the initial points, you can always name your variables matrixA, vectorB, vectorC, or matrixA, b, c if that helps you to convey the mathematical notation better. I think this actually exists in some places in the repository.<div>
<br></div><div>Regarding requirements on comments. We have to be careful how many requirements a module writer is expected to obey. As Jim Miller is fond of saying, to know what a piece of code does, you need to "Read the code". Which is his concise way of noting that comments and descriptions, unless they are generated or automatically verified by the system, will always be out of date and wrong. The more complicated and specific the comments are, the more certain you can be that they will become incorrect after a few modifications to the file, or after the file is used as a template for a new module. So this is an admirable effort, and will greatly improve the quality of the code at least in the short term. However, maintaining it long term argues for minimization of required comments not expansion.</div>
<div><br></div><div>Keep up the good work,</div><div><br></div><div>- Wes<br><br><div class="gmail_quote">On Sat, Dec 12, 2009 at 3:49 PM, David Doria <span dir="ltr"><<a href="mailto:daviddoria%2Bvtk@gmail.com">daviddoria+vtk@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div class="im">On Sat, Dec 12, 2009 at 3:22 PM, Berk Geveci <<a href="mailto:berk.geveci@kitware.com">berk.geveci@kitware.com</a>> wrote:<br>
>>> c) a one line "Necessary libraries: vtkHybrid, vtkWidgets" that tells<br>
>>> the user which libraries they will need to link to in order to use<br>
>>> this class.<br>
>><br>
>> This would certainly be useful, and we have talked about this before. I wonder if this belongs in descriptions of the VTK kits, and<br>
>> whether CMake could take care of some of these lower level details for most projects.<br>
><br>
> I agree that this is useful information to have but I don't think it<br>
> should be manually maintained in the comments. Dependencies changes<br>
> and classes move and manually maintained dependency information is<br>
> surely to become out of sync. This information could probably be<br>
> generated by CMake and then ingested by Doxygen relatively easily.<br>
> That's what I'd suggest doing.<br>
> </div></blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div class="im">> -berk<br>
<br>
</div>1) Good points Berk. Unfortunately I'm neither a CMake nor Doxygen<br>
expert - any volunteers to do this?<br>
<br>
2) Marcus - I've brought up regression testing the examples many<br>
times. I think there are two ways to go:<br>
<br>
a) Put them in the existing VTK/Examples directory<br>
<br>
Benefit - no initial overhead/work<br>
<br>
Drawback - how would users googling for phrases find them? We'd need<br>
to prominently display "See VTK/Examples for many examples!" on the<br>
website.<br>
<br>
b) Make the examples a separate repository (like VTKData) so that<br>
users don't need to download the many examples unless they actually<br>
want them.<br>
<br>
Benefit - Separation of the large database of examples from the main<br>
code. Experienced users can choose to not download them at all.<br>
<br>
Drawback - some initial overhead of setting up a new CVS (or maybe we<br>
could even start these on an SVN server?)<br>
<br>
Bill and I continue to clean up the examples so they meet VTK coding<br>
standards/practices, but it would be some good motivation if when they<br>
are "ready" they could be moved into a regression testing framework.<br>
This is necessary to ensure they live on as the project evolves.<br>
<br>
What do you guys think about either of these?<br>
<br>
Thanks,<br>
<font color="#888888"><br>
David<br>
</font><div><div></div><div class="h5">_______________________________________________<br>
Powered by <a href="http://www.kitware.com" target="_blank">www.kitware.com</a><br>
<br>
Visit other Kitware open-source projects at <a href="http://www.kitware.com/opensource/opensource.html" target="_blank">http://www.kitware.com/opensource/opensource.html</a><br>
<br>
Follow this link to subscribe/unsubscribe:<br>
<a href="http://www.vtk.org/mailman/listinfo/vtk-developers" target="_blank">http://www.vtk.org/mailman/listinfo/vtk-developers</a><br>
<br>
</div></div></blockquote></div><br><br clear="all"><br>-- <br>Wesley D. Turner, Ph.D.<br>Kitware, Inc.<br>Technical Leader<br>28 Corporate Drive<br>Clifton Park, NY 12065-8662<br>Phone: 518-881-4920<br>
</div>