docstrings style question
I've got a series of modules which look like this: # # # Temperature Sense Test # # class Test3(ar_test.AR_TEST): """Temperature Sense Test""" I don't like the duplicated information: But the comment is attractive, and the docstring self.__doc__ is already in use in the test log. I've read that all modules and classes should have docstrings, but I don't really have anything else to say, and each module contains only one class. I don't think that """Temperature Sense Test""" class Test3(ar_test.AR_TEST): """Temperature Sense Test""" would be a real improvement. What do you think? Steve. -- http://mail.python.org/mailman/listinfo/python-list
Re: docstrings style question
"Russ P." <[EMAIL PROTECTED]> wrote in message news:[EMAIL PROTECTED] > On Jan 9, 11:51 pm, Fredrik Lundh <[EMAIL PROTECTED]> wrote: >> Steve Brown wrote: >> > I've got a series of modules which look like this: >> >> > # >> > # >> > # Temperature Sense Test >> > # >> > # >> > class Test3(ar_test.AR_TEST): >> > """Temperature Sense Test""" >> >> > I don't like the duplicated information: But the comment is attractive, >> > and >> > the docstring self.__doc__ is already in use in the test log. I've read >> > that >> > all modules and classes should have docstrings, but I don't really have >> > anything else to say, and each module contains only one class. I don't >> > think >> > that >> >> > """Temperature Sense Test""" >> > class Test3(ar_test.AR_TEST): >> > """Temperature Sense Test""" >> >> > would be a real improvement. >> >> > What do you think? >> >> since you already seem to cater to your audience (clearly marked >> comments for people browsing the code, brief docstrings for the test >> log), I don't really see why you should change anything. >> >> > I've read that all modules and classes should have docstrings >> >> if nobody's going to read them, there's no reason to add them. don't >> treat generic style advice as dogma. >> >> > > Well, trivial modules certainly don't need much documentation, but he > didn't say they were trivial. I assumed there was more to them then he > showed. All of the complexity is in the test framework. I've been working on paring back the tests to make them simple to understand, create and modify, which is how I've come to this: I'm still trying to remove lines. The test itself is a now a linear script of 20-40 lines, and I'm still working on them. However, it is relatively important to make the documentation right for these simple scripts. The docstring/comment does need to show some embedded dependancies, I just chose one without any. I realise from reading Jeroen Ruigrok van der Werven's comment that I should probably also care what epydoc makes of my doc strings, -- that's an additional constraint. -- http://mail.python.org/mailman/listinfo/python-list
Re: docstrings style question
"Neil Cerutti" <[EMAIL PROTECTED]> wrote in message news:[EMAIL PROTECTED] > On Jan 10, 2008 12:47 AM, Steve Brown <[EMAIL PROTECTED]> wrote: >> I've got a series of modules which look like this: >> >> # >> # >> # Temperature Sense Test >> # >> # >> class Test3(ar_test.AR_TEST): >> """Temperature Sense Test""" >> >> >> I don't like the duplicated information: But the comment is attractive, >> and >> the docstring self.__doc__ is already in use in the test log. I've read >> that >> all modules and classes should have docstrings, but I don't really have >> anything else to say, and each module contains only one class. I don't >> think >> that >> >> """Temperature Sense Test""" >> class Test3(ar_test.AR_TEST): >> """Temperature Sense Test""" >> >> would be a real improvement. >> >> What do you think? > > I recommend a careful reading of PEP 257. > > You shouldn't waste your time creating (at best) decorative comments, > like: > # > # > # Temperature Sense Test > # > # > class Test3(ar_test.AR_TEST): > """Temperature Sense Test"" > > Remember that comments have to maintained along with the rest of the > code, so unnecessary ones just create more work for you. Any time you > can replace a comment with self-explanatory code, you should. > > Here's a vast improvement: > > class TemperatureSenseTester(ar_test.AR_TEST): > > -- > Neil Cerutti <[EMAIL PROTECTED]> Yes, I'm working in that direction. At present there is still code that parses the test sequence to get the class name, but I'm rebuilding that. However, there will still be sufficient information for some of the tests to justify one doc string or comment as well as the class name. Is it possible to get from an object to a class module doc string? Something like self.class.module.__doc__ ? I'm not able to do an assignment inside the test class, because I have to keep that clean, but I can do assignments inside the parent test class. Steve -- http://mail.python.org/mailman/listinfo/python-list
Re: docstrings style question
What I'm trying to do with the tests is pare them back so that the code explicitly and concisely documents the tests. 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, a comment like this: i++#next voltage indicates that the author thinks the most complex thing present is the variable mapping. 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. Steve "Martin Marcher" <[EMAIL PROTECTED]> wrote in message news:[EMAIL PROTECTED] > Russ P. wrote: > -- http://mail.python.org/mailman/listinfo/python-list
