Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #55263

Re: python function parameters, debugging, comments, etc.

Show all headers | View raw

Chris Friesen <cbf123@mail.usask.ca> writes:

> I've got a fair bit of programming experience (mostly kernel/POSIX
> stuff in C). I'm fairly new to python though, and was hoping for some
> advice.

Welcome! Thanks for taking the practice of programming seriously enough
to seek improvement.

> Is the recommendation to have comments for each function describing
> the expected args?

Not quite; we don't use comments for that purpose, but docstrings
<URL:http://docs.python.org/3/glossary.html#term-docstring>.

Python docstrings allow documenting the API of modules, classes, and
functions, in such a way that the documentation is right there in the
source code *and* is available at run-time (with the ‘__doc__’ magic
attribute).

PEP 256 <URL:http://www.python.org/dev/peps/pep-0256/> has links to the
various specifications that give detailed information on guidelines for
writing good docstrings, and for how good docstrings will be used by
other tools.

> So what's the recommended way of dealing with stuff like this in
> larger projects with many developers?

Choose community-endorsed standards – the PEPs mentioned above,
referenced from PEP 256 – and discuss the benefits of them with your
team.

-- 
 \     “I think it would be a good idea.” —Mohandas Gandhi (when asked |
  `\                          what he thought of Western civilization) |
_o__)                                                                  |
Ben Finney

Back to comp.lang.python | Previous | Next | Find similar | Unroll thread

Thread

Re: python function parameters, debugging, comments, etc. Ben Finney <ben+python@benfinney.id.au> - 2013-10-02 11:51 +1000

csiph-web