[Bf-committers] Blender roadmap article on code blog

[Jed Frechette]

On Thu, 27 Jun 2013 12:33 Campbell Barton <ideasman42 at gmail.com> wrote

> On Thu, Jun 27, 2013 at 10:58 AM, Jed <jedfrechette at gmail.com> 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