kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@...>]

Dick Hollenbeck wrote:
> 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.

My thinking exactly. If I change this code, I have to remember to
update the comments in two places or at least check to make sure it
isn't defined in the header and the source files.

Wayne

> 
> 
> 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