On Thu, 27 Jun 2013 12:33 Campbell Barton <[email protected]> wrote
> On Thu, Jun 27, 2013 at 10:58 AM, Jed <[email protected]> wrote: >> I agree about the existing >> Python code being hard to read. >Am happy to take criticism for python code, but curious which parts > you found problematic to follow. One particularly crufty bit I was looking at recently is the Smart UV Project module (http://preview.tinyurl.com/ldujq8r). None of the functions have doc strings, large portions of the code are commented out and presumably obsolete, unusual naming conventions, etc. The Lightmap UV unwrapping module is much better but also doesn't have any doc strings. > I've tried to include examples in the text editors templates to help > give users some samples of working scripts, > is there some area you think should be added to here that would help? The examples are very helpful, however most of the time my questions are more Why than How and inevitably about some corner case that isn't quite covered by one of the cookbook recipes. I don't know that this is necessarily a documentation issue as much as I simply haven't committed enough time to fully understanding how Blender's internals work. This certainly goes to David's point about the difficulty of diving in for casual users, unfortunately I don't know how to bypass the learning curve. Fortunately, the last time I spent much time on scripting Blender was ~3 months ago and I remember thinking at the time that the more conceptual API documentation had improved since the last time I looked at it. > I had a quick look over google's standards and while we don't follow > all, a lot of them are aligned with pep8 (and common sense), >if you think there are some we could benefit from, I'd be interested > to know which ones specifically. I like that Google's standard is explicit about how to document things like function arguments and return values, whereas PEP 257 doesn't really give any guidance other than "do it". Numpy's docstring style guide is also quite good about this. I might quibble with some of Google's choices but the main things I like about it for my own projects are that: it is in one place, is pretty comprehensive, I can point someone else to it and expect a reasonable result, and I didn't have to write it. I know Blender has a style guide for C code and it would probably be good to have one for Python, even if it is just a paragraph saying "Follow PEP 8 & 257". > Integrating ipython is fairly straightforward I suspect a lot of users would greatly appreciate IPython's improved object introspection and user friendliness. Cheers, -- Jed Frechette _______________________________________________ Bf-committers mailing list [email protected] http://lists.blender.org/mailman/listinfo/bf-committers
