kicad-developers team mailing list archive

[Dick Hollenbeck <dick@...>]

Wayne Stambaugh wrote:
> JP,
>
> I noticed that you moved the comments I wrote for
> LIB_COMPONENT::LocateDrawItem() from the header file to the source file.
> This comment was formatted for Doxygen to generate source code
> documentation files. Generally speaking, these comments are placed in
> the header file ( see the header files in the wxWidgets source for some
> very good examples ). Doxygen will correctly parse these comments
> whether they are in the header or the source file. In the Kicad source,
> there is no consistency to where Doxygen comments are placed. In some
> cases the same comment is in both the header and the source file. I
> personally prefer them in the header file ( mainly because emacs will
> syntax highlight them when they are in the header ) but more importantly
> I prefer that they be consistent so I know where to look for them. I
> know we currently don't generate source documentation with Doxygen but
> it would be nice to get the code base to the point where we could to
> help out developers. Anyone one else have any thoughts on this? Maybe
> its time to take another look at writing some coding standards.
>
> Wayne

In my opinion they should be ONLY in the header files, simply because I 
do not like to MAINTAIN two copies. For me it is about maintenance 
simplicity. I would rather have to go to the header file than have two 
dis-agreeing copies, one in the header and one in the source file, or to 
have to burden of keeping them in sync. All the code I have written in 
the project conforms to this.


In this regard, Java is a step forward over C++ : no header files. So 
in that case, the comments can go right with the code.

Java is pretty nice for application development.


Dick