On Fri, 2002-11-22 at 16:28, Matthew Vanecek wrote: > I whole-heartedly agree. There are several great tools for creating API > references (e.g., javadoc, doxygen, etc). My suggestion is to decide on > which tool would be best, and to create a standards doc. with comment > structure the #1 item in it.
Agreed. > As code is worked, the developer should > make an effort to put the comments into the standard format such that > the document tool can pick them out. I think a mass update of > *everything* probably is very difficult to engineer. Its not hard to run through and comment all the functions in a file while you are working there. > All new > code/patches should be checked for properness before being committed. > It may also be a good time to standardize on a coding style to (e.g, GNU > vs K&R). Pick one. My only 'requirement' is that the opening brace of a function be in column 0 so that the emacs beginning-of-defun function will work properly. Drives me crazy when I type C-M-a and end up at the beginning of the file instead of the beginning of the function. > indent works wonders for massaging code into a single style... :-) I'll even volunteer to handle the process, and put in the proper incantation so that emacs knows what the indentation should be. > I really like Benoit's suggestion of moving documentation to > header/source comments, because it's much more likely to be kept > up-to-date there, than if it were a separately maintained entity. Source please, not header. I know there are currently lots of comments in header files, but I prefer comments closer to the actual code and I think the are more likely to be updated there. How much of your time do you spend editing .c files vs. .h files? David
signature_asc_DEFANGED-22108.DEFANGED-41
Description: application/defanged-41
