[Bf-committers] Summer of Documentation

[Alexander Ewering]

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