docstrings style question

[Steven D'Aprano]

On Fri, 11 Jan 2008 13:09:26 +1100, Steve Brown wrote:

> What I'm trying to do with the tests is pare them back so that the code
> explicitly and concisely documents the tests.

Yes, this is good.


> It is important that the comments and doc strings NOT contain
> information about how Temperature Sense works because that is outside
> the scope of the test.
> 
> More generally, comments like this
> 
>     i++            #increments i
> 
> indicate that the author thinks that the most complex thing present is
> the syntax, 

I would suggest that it indicates an author who hates writing  
documentation, but has been told that (s)he *must* do it.

That is the archetypal example of the pointless comment that is worse 
than no comment at all.


> a comment like this:
> 
>     i++            #next voltage
> 
> indicates that the author thinks the most complex thing present is the
> variable mapping.

To me, that indicates the author both hates writing documentation, and 
either can't think of descriptive variable names, or refuses to use them 
out of some misguided sense of "optimization".


> For the readers and maintainers of these tests, the most complex thing
> present is the syntax, not the test logic, so if I need to add more
> documentation, it will look like this:
> 
> # Temperature Sense Test
> # Lines starting with # are comments
> # Variables are case sensitive
> # Tab characters will break this file
> 
> -- and go from there.

Your trusting your production code to developers who don't even know the 
most basic elements of syntax like what is a comment? That's pretty 
foolh^H^H^H^H^H brave.



-- 
Steven