[vtk-developers] inlined function comments

David Doria daviddoria+vtk at gmail.com
Wed Dec 9 18:07:29 EST 2009


As an example, in vtkMath.h, there are many functions defined after
the end of the class. Some of these have comments:

//----------------------------------------------------------------------------
// Cross product of two 3-vectors. Result (a x b) is stored in z[3].
inline void vtkMath::Cross(const float x[3], const float y[3], float z[3])
{
  float Zx = x[1] * y[2] - x[2] * y[1];
  float Zy = x[2] * y[0] - x[0] * y[2];
  float Zz = x[0] * y[1] - x[1] * y[0];
  z[0] = Zx; z[1] = Zy; z[2] = Zz;
}

and some don't

//----------------------------------------------------------------------------
inline float vtkMath::RadiansToDegrees()
{
  VTK_LEGACY_REPLACED_BODY(vtkMath::RadiansToDegrees, "VTK 5.4",
                           vtkMath::DegreesFromRadians);

  return vtkMath::DegreesFromRadians( 1.f );
}

Should we comment them all with the same comments that were used in
the function declarations for consistency? It seems to have been
arbitrarily decided which functions are "complicated enough" to
warrant a comment. It doesn't look like these are used in the doxygen,
but I think this would improve code readability.

Thoughts?

Thanks,

David



More information about the vtk-developers mailing list