On Thu, 2002-11-07 at 21:05, Andre Poenitz wrote: > 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... Fine, people can do that. The doxygen code to grep for is \todo .
> > > * 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. There is no way for the compiler to check that the subroutine does what it was supposed to do, either. And there is no way for the reader of the code to guess why something was done in a particular way unless it was documented. > > - 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. Agreed. That is why the comments should say what the code cannot - the why, the in and the out, and leave the *how* to the code itself. > > 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. This does not aid a programmer who is looking to *use* a function or to rapidly grasp the purpose of a class or method. > > 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. This problem is addressed by the documentation scheme I originally proposed. The header retains concise, compact comments, and the longer stuff is placed in the .C file where you usually have to scroll to read the code anyway. > > > 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. I tend to agree with this statement; my example was contrived. However, variables are often poorly named. There are often pre-conditions which should exist before calling a method. How the method fits into the big picture is useful. These things are not, and can not be, described by the code. Please remember that I am doing this so that I can understand the code and obtain feedback on my understanding of how things in LyX work. So far there has been a lot more words spent on the nature of comments and whether they are worthwhile at all. For example, I do not yet know if my understanding of LyXTextClass is correct or way off the mark. The fact that there are several possible interpretations of the aim of the code (especially viewing just the header file) further invalidates the narrow view of comments described above. Based on feedback here, I will aim for fairly complete short comments, i.e. /// style, in the header file. These should be adequate to the requirements expressed here. I would like to have *some* longer comments describing the quirks of methods, where necessary, in the .C files. I do not aim to make these comments complete. To those who prefer to see documentation in the .h file, I refer them to the short comments I will put there. I will make a new patch. Ben.
