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

[Marcus D. Hanwell]

On Sat, Dec 12, 2009 at 10:23 AM, David Doria
<daviddoria+vtk at gmail.com<daviddoria%2Bvtk at gmail.com>
> wrote:

> On Sat, Dec 12, 2009 at 10:17 AM, Francois Bertel
> <francois.bertel at kitware.com> wrote:
> > Arguments of functions and methods in VTK start with lowercase. So
> > it's is not OK. Only the variable member of a class start with an
> > upper case.
>
> It seems very annoying to not comply with mathematics notation, which
> is clearly more standard than VTK notation.
>
> The mathematical notation is there to make it clear that the variable in
the formula is a matrix, this is C++ code in a matrix class, which already
makes it clear that these variables are concerned with matrix algebra.

It is fine in the comments to use conventional mathematical notation, but I
agree with Francois that the code should stick to VTK coding conventions
wherever possible. Having comments inside of a //BTX //ETX block does not
present any issues.

I think the comments are a little on the verbose side, I would rather go
into detail about how the matrix is laid out in memory in the class
description, and then the individual function documentation can be much
briefer. So explain row major order, assume the reader knows about matrix
algebra in the class description and then keep brief function descriptions.

How does that sound? I am hoping to add some more inline doxygen code
examples to some of the new code I have added, examples of which can already
be seen (not by me) in the OpenGLExtensionManager header.

Marcus
-- 
Marcus D. Hanwell, Ph.D.
R&D Engineer, Kitware Inc.
(518) 881-4937
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20091212/095c190c/attachment.html>