On Thu, Nov 07, 2002 at 11:11:46PM +1100, Ben Stanley wrote: > 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.
No. The code _is_ the documentation. If it is unreadable, it is broken. I know that we do not live in an ideal world, though, and LyX code _is_ broken by this standard. But instead commenting the broken code, the code should be fixed. > > 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 purpose of a class should be documented in the comment in front of the class definition. > 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. If scrolling is needed, the functions are too big... [ideal world, again] > I tend to agree with this statement; my example was contrived. However, > variables are often poorly named. [Which lead very recently to some confusion btw...] > 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 think we could reach consensus on this one ;-) > 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. Fine. > I will make a new patch. Thank you. Andr'e -- Those who desire to give up Freedom in order to gain Security, will not have, nor do they deserve, either one. (T. Jefferson)
