Documenting Regex (and code)

[Richard Parker]

-----------------------------------------------------------------------------------------
Dense and complex REs are quite powerful, but may also contain
and hide programming mistakes.  The ability to describe what is
intended -- which may differ from what is written -- is useful.
-----------------------------------------------------------------------------------------
Once again, I feel compelled to stress the importance of well-written documentation embedded within the program's code. Many of you eschew this practice, stating that when the code is changed that often the documentation isn't. Shame on you! Documentation is at least, or more, important than the code, as it reflects the intentions of the creator. Failing to revise documentation along with it's accompanying code is an egregious sin and is one for which all programmers should repent.

After more than five decades of programming, documenting my code, writing books about programming and it's documentation, I shudder at the thought of even one of you thinking that removal of all the comments before modifying a program is appropriate, that the code itself properly expresses it's creator's intent.

I accept the flames that will ensue from this post and remain steadfast in my belief and extensive experience that commented (in the form of block comments) code is far more valuable than just the code itself.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20110606/783c87c8/attachment.html>