Are code assertions considered harmful?

[Richard Sharpe]

On Sat, 8 Nov 2003, Cameron Paine wrote:

> I'm interested in opinions from a group of seasoned designers and
> coders...
> 
> I'm hunting some undocumented features in libsmbclient that are really
> laying my project's financial and time lines to waste. I guess I should
> have done a thorough code review before I committed to using the library
> so I guess that after 25 years at this I'm still able to be ambushed. ;-)

What undocumented features ...?
 
> Anyway, I'm trying to improve the worst excesses of the code and am
> being hamstrung by the paucity of documentation. It seems that the
> interface contracts for most of the functions in the library--both
> internal and exported--are seldom written down. I guess those of you
> who have worked on this code are in physical proximity and/or have
> developed good interpersonal communication and the nod and wink
> approach has reduced the time to implement. However as a latecomer
> who wants to: a) get his project delivered thereby reducing his
> financial exposure and; b) return the fruits of this labour to the
> community, the opacity of some of the contracts is really taking a
> toll.

Actually, we are spread around the world, but we are in email and 
sometimes IRC contact.

> To my question then: why are assertions considered unhelpful? I have
> found none so far and several of the thorny features I've found
> would have been detected if the original coder had stated his
> assumptions, as code, using assert() or an equivalent. Twice I've
> been tempted to put a couple in but I've baulked because this does
> not seem to be the "Samba Way".

Assertions are not considered unhelpful. At work they are often very 
helpful. However, you will find very few in the two open source projects I 
work on. Perhaps it is the nature of those projects.

> Also, I understand the traditional (and lame IMO) argument for not
> documenting code. And yes, I can read C better than I can read my
> own handwriting. However, when the code implements conflicting
> behaviours, how can the maintainer know which was the intended one
> and which one slipped through the cracks in the testing regime.

What conflicting behavio[u]rs?

> While on the subject of code commentary, what is the attitude of
> the team to others adding commentary to their code? So far I've
> amassed a dozen pages of explanatory notes that I'm keeping
> separate from the code. I'm doing this primarily so I don't
> pollute the code with (possibly incorrect) statements about
> intended behaviour. I could mitigate against this by documenting
> what the code does (not what people seem to assume that it does)
> but that may then create conflicts with the small amount of doco
> that does exist.

You are more than welcome to submit documentation in the form of comments. 
I will look through them and commit them if I am happy with them.

Howeevr, please tell us more about the problems you are experiencing.

Regards
-----
Richard Sharpe, rsharpe[at]ns.aus.com, rsharpe[at]samba.org, 
sharpe[at]ethereal.com, http://www.richardsharpe.com