Mercurial > pylearn
comparison doc/v2_planning/coding_style.txt @ 1144:1679742e7aa1
Writing related to the tasks assigned to me at today's meeting.
| author | David Warde-Farley <wardefar@iro.umontreal.ca> |
|---|---|
| date | Thu, 16 Sep 2010 16:10:10 -0400 |
| parents | 6c79394b6b20 |
| children | f6011a2aff0b |
comparison
equal
deleted
inserted
replaced
| 1143:fa1715e759e3 | 1144:1679742e7aa1 |
|---|---|
| 518 * Look into recommendations on how to document a class, method, ... | 518 * Look into recommendations on how to document a class, method, ... |
| 519 * Write recommendations on when to use logging vs. warning | 519 * Write recommendations on when to use logging vs. warning |
| 520 * Make public some configuration files / plugins for vim | 520 * Make public some configuration files / plugins for vim |
| 521 * Come up with official common file header (license in particular) | 521 * Come up with official common file header (license in particular) |
| 522 | 522 |
| 523 | 523 Extended docstring standard (DWF) |
| 524 --------------------------------- | |
| 525 | |
| 526 In addition to the general guidelines of PEP 257, it is advised that we adopt | |
| 527 the NumPy docstring standard, or at least use it as a basis for formulating | |
| 528 our own. | |
| 529 | |
| 530 Read the detailed docstring standard at | |
| 531 | |
| 532 http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard | |
| 533 | |
| 534 | |
| 535 logging module, the warning module, and when to use which | |
| 536 --------------------------------------------------------- | |
| 537 | |
| 538 The logging module | |
| 539 ################## | |
| 540 | |
| 541 A central logging facility for Python capable of logging messages of various | |
| 542 categories/urgency and choosing with some granularity which messages are | |
| 543 displayed/suppressed, as well as where they are displayed or written. This | |
| 544 includes an "INFO" level for innocuous status information, a "WARNING" level | |
| 545 for unexpected state that is still recoverable, "DEBUG" for detailed | |
| 546 information which is only really of interest when things are going wrong, etc. | |
| 547 | |
| 548 In addition to the `library documentation`_, see this helpful tutorial, | |
| 549 `Python Logging 101`_. | |
| 550 | |
| 551 .. _library documentation: http://docs.python.org/library/logging.html | |
| 552 .. _Python Logging 101: http://plumberjack.blogspot.com/2009/09/python-logging-101.html | |
| 553 | |
| 554 The warning module | |
| 555 ################## | |
| 556 | |
| 557 The warning module in the standard library and its main interface, the | |
| 558 warn() function, allows the programmer to issue warnings in situations where | |
| 559 they wish to alert the user to some condition, but the situation is not | |
| 560 urgent enough to throw an exception. By default, a warning issued at a given | |
| 561 line of the code will only be displayed the first time that line is executed. | |
| 562 By default, warnings are written to sys.stderr but the warning module | |
| 563 contains flexible facilities for altering the defaults, redirecting, etc. | |
| 564 | |
| 565 Which? When? | |
| 566 ############ | |
| 567 | |
| 568 It's our feeling that the logging module's WARNING level be used to log | |
| 569 warnings more meant for *internal*, *developer* consumption, to log situations | |
| 570 where something unexpected happened that may be indicative of a problem but | |
| 571 it's several layers of abstraction below what a user of the library would | |
| 572 care about. | |
| 573 | |
| 574 By contrast, the warning module should be used for warnings intended for user | |
| 575 consumption, e.g. alerting them that their version of pylearn is older than | |
| 576 this plugin requires, so things may not work as expected, or that a given | |
| 577 function/class/method is slated for deprecation in a coming release (early | |
| 578 in the library's lifetime, DeprecationWarnings will likely be the most common | |
| 579 case). The warning message issued through this facility should avoid | |
| 580 referring to pylearn internals. | |
| 581 | |
| 582 Suggested per-file boilerplate | |
| 583 ------------------------------ | |
| 584 | |
| 585 """Module docstring as the first line, as usual.""" | |
| 586 | |
| 587 __authors__ = "Olivier Delalleau, Frederic Bastien, David Warde-Farley" | |
| 588 __copyright__ = "(c) 2010, Université de Montréal" | |
| 589 __license__ = "3-clause BSD License" | |
| 590 __contact__ = "Name Of Current Guardian of this file <email@address>" | |
| 591 | |
| 592 We could also pull Mercurial revision info and put it in __version__, this | |
| 593 seems to be common. |