Re: Tutorials and "from foo import *"

On 11-10-23 11:11 PM, Derakon wrote:
> I decided it was time to start taking my OpenGL knowledge past the
> textured quads I'd needed for my 2D work, so I looked up tutorials on
> shaders, and found this:
>
> http://pyopengl.sourceforge.net/context/tutorials/shader_1.xhtml
>
> Now, regardless of your opinion on how terse or verbose a language
> should be, I think we can all agree that clarity is vital for
> tutorials. The reader doesn't know what's going on, so the code needs
> to be as explicit as possible; otherwise the reader just ends up
> confused. Terseness is often an anti-virtue here. So it's a bad sign
> when that tutorial leads off by importing * from a bunch of modules.
> The problem with importing * is that you then have no idea where a
> given symbol comes from. Where did compileShader originate?
> glUseProgram? GL_FRAGMENT_SHADER? And so on. The author of the
> tutorial presumably knows, and very likely anyone with any experience
> with PyOpenGL would also know, but those aren't the target audience
> here. The people reading this code will want to be able to adapt it to
> their own needs, and that's harder when
>
> So I'd like to request that someone with the appropriate knowledge and
> access change all of the imports to either import the specific
> components needed (as in "from OpenGL.arrays import vbo" in that
> tutorial) or simply import the module and then refer to it by name
> ("import OpenGLContext; BaseContext =
> OpenGLContext.testingcontext.getInteractive()").
>
> And yes, this extends to all of the things under the OpenGL.GL
> namespace. Reduction to "import OpenGL.GL as GL" is fine, but some
> explicit namespace still needs to be there (or else the "from foo
> import specific items" approach). Yes, it'll result in a lot of
> silly-looking things like "GL.GL_TRIANGLES", but silly is far better
> than obscure when it comes to tutorials.
>
> Otherwise, this looks like it should be a very useful tutorial; my
> thanks to whoever wrote it.
I'd be hesitant to adopt that style for the code, as it is non-idiomatic
wrt general PyOpenGL code.  That said, explicitly referencing the
shaders.* entry points might make sense (they are about the only entry
points which don't follow the "if it starts with gl or GL_ it comes from
OpenGL.GL, if it starts with glu or GLU_ it comes from OpenGL.GLU, if it
starts with glut or GLUT_ it comes from OpenGL.GLUT" rule).  That said,
they are *intended* to override the OpenGL.GL namespace variants on
import to make it easier to use the "core" functions on older hardware.

Further discussion of where entry points are coming from is also quite
possible.  I'll look into adding it.

Have fun,
Mike

-- 
________________________________________________
  Mike C. Fletcher
  Designer, VR Plumber, Coder
  http://www.vrplumber.com
  http://blog.vrplumber.com


------------------------------------------------------------------------------
The demand for IT networking professionals continues to grow, and the
demand for specialized networking skills is growing even more rapidly.
Take a complimentary Learning@Cisco Self-Assessment and learn 
about Cisco certifications, training, and career opportunities. 
http://p.sf.net/sfu/cisco-dev2dev
_______________________________________________
PyOpenGL Homepage
http://pyopengl.sourceforge.net