[vtk-developers] comments inside BTX ETX + matrix variable naming

[Wes Turner]

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.

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.

Keep up the good work,

- Wes

On Sat, Dec 12, 2009 at 3:49 PM, David Doria
<daviddoria+vtk at gmail.com<daviddoria%2Bvtk at gmail.com>
> wrote:

> On Sat, Dec 12, 2009 at 3:22 PM, Berk Geveci <berk.geveci at kitware.com>
> wrote:
> >>>    c) a one line "Necessary libraries: vtkHybrid, vtkWidgets" that
> tells
> >>>   the user which libraries they will need to link to in order to use
> >>>   this class.
> >>
> >> This would certainly be useful, and we have talked about this before. I
> wonder if this belongs in descriptions of the VTK kits, and
> >> whether CMake could take care of some of these lower level details for
> most projects.
> >
> > I agree that this is useful information to have but I don't think it
> > should be manually maintained in the comments. Dependencies changes
> > and classes move and manually maintained dependency information is
> > surely to become out of sync. This information could probably be
> > generated by CMake and then ingested by Doxygen relatively easily.
> > That's what I'd suggest doing.
> >
>
> -berk
>
> 1) Good points Berk. Unfortunately I'm neither a CMake nor Doxygen
> expert - any volunteers to do this?
>
> 2) Marcus - I've brought up regression testing the examples many
> times. I think there are two ways to go:
>
> a) Put them in the existing VTK/Examples directory
>
> Benefit - no initial overhead/work
>
> Drawback - how would users googling for phrases find them? We'd need
> to prominently display "See VTK/Examples for many examples!" on the
> website.
>
> b) Make the examples a separate repository (like VTKData) so that
> users don't need to download the many examples unless they actually
> want them.
>
> Benefit - Separation of the large database of examples from the main
> code. Experienced users can choose to not download them at all.
>
> Drawback - some initial overhead of setting up a new CVS (or maybe we
> could even start these on an SVN server?)
>
> Bill and I continue to clean up the examples so they meet VTK coding
> standards/practices, but it would be some good motivation if when they
> are "ready" they could be moved into a regression testing framework.
> This is necessary to ensure they live on as the project evolves.
>
> What do you guys think about either of these?
>
> Thanks,
>
> David
> _______________________________________________
> Powered by www.kitware.com
>
> Visit other Kitware open-source projects at
> http://www.kitware.com/opensource/opensource.html
>
> Follow this link to subscribe/unsubscribe:
> http://www.vtk.org/mailman/listinfo/vtk-developers
>
>


-- 
Wesley D. Turner, Ph.D.
Kitware, Inc.
Technical Leader
28 Corporate Drive
Clifton Park, NY 12065-8662
Phone: 518-881-4920
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20091213/bd2c60c7/attachment.html>