Tim Rentsch
6/27/2011 8:38:00 PM
Shao Miller <sha0.miller@gmail.com> writes:
> On 6/25/2011 12:44 PM, Tim Rentsch wrote:
>> Shao Miller<sha0.miller@gmail.com> writes:
>>
>>> Where one uses macros instead of jump statements (though the actual
>>> statements _could_ be overridden, theoretically) and where one uses
>>> the 'HAS_CLEANUP' macro within whatever scopes require resource
>>> cleanup.
>>>
>>> Feedback welcome and appreciated, as always.
>>> [snip posted source]
>>
>> It would be TREMENDOUSLY helpful to take a different approach to
>> documentation style. For example,
>>
>> /*
>> Several prose paragraphs, giving problem statement,
>> basic approach, perhaps a short list of primary
>> functions or other elements.
>> */
>>
>
> Ok. Thanks.
>
>>
>> #if 0 /* Example uses */
>>
>> ... some simple but illustrative examples ...
>>
>> #endif
>>
>
> Ah yes. Good idea.
>
>>
>> /* Description of interface elements, entry points:
>>
>> name1 discussion/explanation
>>
>> name2 discussion/explanation
>>
>> ... other macro names, type names, function names, etc ...
>>
>> */
>>
>
> Is this really different than what I've got? I guess you are
> suggesting that it all be grouped together within a single comment?
Yes, and laid out in this way, and giving just a
description of interface, with no implementation.
>> ... declarations (without contents) of public struct types ...
>
> Well, yes. I normally do:
>
> typedef struct s_xxx_ s_xxx
The key thing is that the types be declared, not whether
typedef's are used to declare them. (If there are other
relevant types that's aren't struct/unions, typedefs for
those should be here also.)
>> ... public function prototypes ...
>>
>
> And then use 's_xxx' in the public function types and/or
> declarations. Since this example had a single, simple, public
> structure type, the definition was nearby (just above it, if I recall
> correctly).
The function prototypes, which are interface, should come
before the definition of structure contents, which are
implementation (as I understand what you are trying to
provide).
>> ... now give code with "as few comments as necessary" ...
>
> Is that really different than what I've got?
Yes, emphatically yes.
[snip]
>> Most of the comments in the posted source are either unnecessary
>> or misplaced.
>
> Uh oh. "Most"?
Yes, it's an English word meaning 'the majority of'.
>> More specifically, comments related to _interface_
>> should be separated from _implementation_ (and all comments
>> pertaining to interface should come before any code containing
>> implementation).
>
> Hmmm...
>
> 'cleanup.h' defines some macros. Yes, the comments are near the
> implementation. So ok, I'll try to remember to take your advice for
> the next time, and throw macro documentation somewhere separately.
>
> If you look at any of my other posted code examples, you'll find that
> comments precede function declarations (or types) in the header. So I
> do [try to] keep that as a habit. If I understand your criticism
> here, it's about not using that habit for these macros (the functions
> are all private).
My suggestions are primarily generically these:
1. All description of interface should precede all source code
supplying implementation. Naturally some of the implementation
source code will duplicate some information already given in
the interface section (such as tags of struct types), but that
consequence is secondary to the principle of giving interface
separately from implementation.
2. Layout and presentation are important; the examples I
gave offer some (what I think are) improvements.
3. Even within the implementation section, a good prose
summary description generally provides more value than
lots of individual, highly localized comments. "A good
overview is worth more than 10,000 per-line comments."
>> A developer wanting to use this package should
>> be able to read just that part describing the interface, and
>> nothing in the implementation, and know enough to start using it.
>
> I really thought a developer might benefit from seeing the brief macro
> implementations right there, [snip]
Just the opposite: a developer will benefit from _not_ seeing
the implementation as much as that is possible. Look up
Parnas's papers on information hiding, and read Fred Brooks's
comments related to that in the 20th anniversary edition of "The
Mythical Man-Month".
> Thanks for reviewing! [snip]
You're welcome, I'm glad you found it helpful.