Bob Carlson wrote:
I believe Kevin said that he always comments code that is not self-explanatory and provides documentation by and for developers. He considers the existing comments to be sufficient for a "non-casual" reader. I believe it was also Kevin who was using an example of dial plan code. He said something to the effect that "If you just know the context of dial plan modules, you don't need any commentary." This is exactly the problem. The comments that are missing are those that provide the context, the overview. No one, least of all me, wants comments of the variety "i++; /* increment counter */". I want to know the intent behind the interface, the rules, the options and the illegal combinations.
That's fine, but why does that need to be in the code that's being _called_? (Your original example was func_callerid.c, which makes very few API calls of its own).
The 'context' of func_callerid.c is a given, there is no need for comments to say "this is a dialplan function, look in pbx.c for the functions that call the functions provided here". In fact, if you start with ast_custom_function_register, that will lead you to pbx.c, and 'struct ast_custom_function'. If you look at all functions in pbx.c that deal with 'struct ast_custom_function', you will see the registration/deregistration functions, the lookup function, and the functions that make the read/write calls. Please tell me where additional comments would have been helpful there, other than saving you a 5-second grep search (or if you use ctags/etags, a zero-second tag lookup).
Also, 'make progdocs' (with doxygen and graphiz installed) is very helpful as well, because it will tell you what functions call what other functions (although not via function pointers, obviously).
_______________________________________________
Asterisk-Dev mailing list
[email protected]
http://lists.digium.com/mailman/listinfo/asterisk-dev
To UNSUBSCRIBE or update options visit:
http://lists.digium.com/mailman/listinfo/asterisk-dev
