[Bf-committers] Summer of Documentation

[Gilbert, Joseph T.]

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)
should 
> 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
useless.

There are comments like "void borderselect(void) /* This function does
the
borderselect command */" in the code, and these are exactly the result
from
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
do
something in the codebase in spite of this lack.
The purpose of comments in source code is not to teach everyone and his
dog
programming. Thorough programming experience is a definite prerequisite
already for touching something as complex as Blender (which could
probably
easily be counted to the Top 10 most complex programs in this universe
and
thus is a bad starting point for first programming experiments), and
comments are meant to explain things that are not *obvious* to
*experienced*
programmers. MOST IMPORTANTLY: Comments don't explain the CODE ITSELF,
but
the underlying MEANING of what it DOES and HOW it does it (in an
ABSTRACT
way, away from the implementation and the actual code). Your problem
lies
deeper. It's not just that you don't understand the implementation and
the
big picture, you don't even understand the code itself - which code
comments
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
http://projects.blender.org/mailman/listinfo/bf-committers