[Bf-committers] Summer of Documentation

Gilbert, Joseph T. jgilbert at tigr.ORG
Mon May 15 16:56:37 CEST 2006

It should be the responsibility of the developer to properly comment his
OWN work. If the original programmer doesn't comment his own code,
that's bad form. Especially for an open source program where other
people will need to understand this code! 

Personally I think good method names and good variable names can be more
helpful than source comments. I find source comments only useful for
'big-picture' ideas about a section of code. (thx ton)

void create_render_object(){} should tell you the story :)

I think ton's struct diagrams and overall views of 'how stuff works'
pages on the wiki are the best resource when trying to get a grasp of
how to work with the source code. 

-----Original Message-----
From: bf-committers-bounces at projects.blender.org
[mailto:bf-committers-bounces at projects.blender.org] On Behalf Of
Alexander Ewering
Sent: Monday, May 15, 2006 3:51 AM
To: bf-blender developers
Subject: Re: [Bf-committers] Summer of Documentation

On Sun, 14 May 2006, Joe Eagar wrote:

> I think anyone interested in commenting parts of the sourcebase
(whether as 
> part of the Summer of Documentation or purely on their own initiative)
> post to this list for approval, find someone to help keep them
straight, and

I find anyone apart from the original coder commenting code totally

There are comments like "void borderselect(void) /* This function does
borderselect command */" in the code, and these are exactly the result
such "Let's just comment something everyone understands" attempts.

OF COURSE "void borderselect()" does NOT cook spaghetti.

tripdragon, probably what you are looking for is comments extensive
enough to
cover your general lack of programming experience in order to be able to
something in the codebase in spite of this lack.
The purpose of comments in source code is not to teach everyone and his
programming. Thorough programming experience is a definite prerequisite
already for touching something as complex as Blender (which could
easily be counted to the Top 10 most complex programs in this universe
thus is a bad starting point for first programming experiments), and
comments are meant to explain things that are not *obvious* to
programmers. MOST IMPORTANTLY: Comments don't explain the CODE ITSELF,
the underlying MEANING of what it DOES and HOW it does it (in an
way, away from the implementation and the actual code). Your problem
deeper. It's not just that you don't understand the implementation and
big picture, you don't even understand the code itself - which code
are not even intended to explain. That's what your favourite C book and
tutorials does/do.

| alexander ewering              instinctive mediaworks
| ae[@]instinctive[.]de   http://www[.]instinctive[.]de
Bf-committers mailing list
Bf-committers at projects.blender.org

More information about the Bf-committers mailing list