Russ P. wrote: > On Jan 9, 9:47 pm, "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?
It's still duplicated information. > I tend to be a bit skimpy with one-line comments for classes and > methods, but I think a more complete (""" style) comment is often > appropriate for the top of the file. > > I'm sure you can think of more to say than "Temperature Sense Test." exactly my opinion > What temperature? What kind of temperature sensor? What kind of test > is it, and why are you doing it? That may all be obvious in context, > but you've provided no context in your post. Also, if the module is of > any significant size, you might want to provide a clue about who wrote > it. Then, if someone has a question about it later, they will know who > to ask. I tend to mention the main use cases for test classes (especially) and also a "human readable" description of what can happen (forgive me the missing line breaks). Something like this: class Test3(ar_test.AR_TEST): """Temperature Sense Test. This class assures that the connection to the hardware sensor can be established. It also checks a reference sensor that always reports a certain value so that one can be sure correct data values are reported. """ hth martin -- http://noneisyours.marcher.name http://feeds.feedburner.com/NoneIsYours You are not free to read this message, by doing so, you have violated my licence and are required to urinate publicly. Thank you. -- http://mail.python.org/mailman/listinfo/python-list