On Thu, Nov 07, 2002 at 12:34:56PM +1100, Ben Stanley wrote:
> I will try to separate these things then, or at least put in \todo
> comments where the code looks iffy and then go back to clean code later.
> Doxygen can generate a page of \todo items, which makes these things
> easy to find.
I believe people are more likely to do a 'grep TODO *.C' than to run
doxygen and look at .html files containing exacly the same information...
> * Load the LyX document file, stored in .lyx format.
> * After loading, the document is completely represented in memory
> * using the internal LyX representation.
> * \param filename the name of the file to read, with complete path.
> * \return true if any error occurred
> * \author someone who wrote this function
> */
> The first style is a summary comment, and I use these in class
> declarations, i.e. header files. The second comment type is the in depth
> documentation, which I place above the function definition.
Ok... I think I have to revert my initial positive response to the idea
then. Adding these "in depth documentation" is BAD for the following
reasons:
- there is no way for the compiler to check whether the code does
what the comment says.
- the comments eat real screen estate and do not add anything to the
understanding of the code
Keeping comment and code onsistent is impossible without using a very
strict commit policy, which in turn would be a pain in the ... to establish
and to follow. Moreover, it eats developer's time and is NO FUN.
If comments are out-of-sync with the code, they are worse than no comments.
IMNSHO the only reason to put comments in the .C are to document
weird tricks where behaviour is non-obvious, and to temporarily disable
debug code.
The "real screen estate" issue is important, too. I can only grasp what I
see. If I have to scroll, I have a puzzle - an additional burden.
> Placing the documentation closer to the code which it describes means
> that it is also more likely to be maintained as the code is modified.
> This is an important consideration.
Code does not have to be described, it has to describe itself. So if you
want to pass an absolute path, call that thing 'string const &
absolute_path' and be done.
Andre'
--
Those who desire to give up Freedom in order to gain Security,
will not have, nor do they deserve, either one. (T. Jefferson)
