[Bf-committers] Blender roadmap article on code blog

[Campbell Barton]

On Fri, Jun 28, 2013 at 7:13 AM, Jed Frechette <jedfrechette at gmail.com> wrote:
> 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.

Both these scripts suffer from 2.4x -> 2.5x-rna -> 2.6x-rna-ngons.
2.5x+ api's for mesh manipulations use RNA and are very limited, 2.4x
was more flexible and had more useful functionality built-in.

However it was always my intention with 2.5x to use bmesh-python
whenever mesh editing needed to be done from Python, it just played
out that by the time we got this BMesh-API available, the scripts you
mention were working with RNA-API and theres not much incentive to
rewrite - only for the sake of cleaner code.

If I needed to make any significant changes to these script's Id
rewrite them for sure.

To see the the difference between a script written using RNA-API's and
BMesh-API, check these 2 scripts (both do a vertex dirt-map effect and
are fairly similar)

rna: https://svn.blender.org/svnroot/bf-blender/trunk/blender/release/scripts/startup/bl_operators/vertexpaint_dirt.py
bmesh: https://svn.blender.org/svnroot/bf-extensions/contrib/py/scripts/addons/oscurart_worn_edges_map.py


>> 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.

Afraid every time I try do something non-trivial in someone else's
open-source project (non-blender), its pretty steep learning curve
too, getting from some template/example code to something useful is
just tricky and theres so much assumed knowledge about how components
work together, what kind of patterns your expected to use etc...
Not to be dismissive and put this in the `too hard` basked, but if new
devs want to contribute to an advanced graphics app, they can expect
to have to get their hands dirty a bit...
(unless we attempt to hide details and expose simple API's - 2.4x
attempted this with its Python API and it didn't work so well, of
course we could try again).

Nevertheless, your point is well taken. That our existing code is not
always so readable and it makes it harder to learn by example.

>> 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.

Currently we use sphinx style comments, but this is only used for API
functions in modules intended to be re-used by other scripts, eg:
http://www.blender.org/documentation/blender_python_api_2_67_release/bpy.utils.html

For functions local to a file they often aren't commented much. I can
see why you might like comments here but I would leave this up to the
author of each script to choose how much to comment internal
functions, classes etc - rather then defining a policy (for the moment
at least).

> 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".

Yep, this should be set out more clearly in our wiki docs (added to my
todo list)

>> Integrating ipython is fairly straightforward
>
> I suspect a lot of users would greatly appreciate IPython's improved
> object introspection and user friendliness.

Also added to rainy-day-todo :)

> Cheers,
>
> --
> Jed Frechette
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at blender.org
> http://lists.blender.org/mailman/listinfo/bf-committers



-- 
- Campbell