Re: [DUnit-interest] RE: Cannot Open API Docs

[Chris M. <ch...@cl...>]

Juancarlo A=F1ez wrote:

>Kristopher,
>
> =20
>
>>And therefore, it is IMO better to *consistently* specify=20
>>functions' characteristics in adjacent comments - even for the=20
>>apparently trivial/obvious cases - better than relying on the=20
>>intention or assumption that one's chosen function signature=20
>>will be completely self-explanatory for the users.
>>   =20
>>
I rarely trust comments. If the comment is trivial, then the code will=20
be, too and I don't need the comment. If the comment is not trivial,=20
than neither is the code and if I really want to be sure, I'll grok the=20
code and skip the comment.

In cases where the code is not self-explanatory, due to working around=20
an external bug or somesuch -- then I'll trust the comment that explains=20
the weirdness.

But having an understood policy of complete comments I think is=20
ultimately futile (how do you ensure it gets done?) and unnecessary=20
(comments can't really be trusted to reflect what the code actually does)=
.

--=20

Chris
http://clabs.org/blogki