Re: Refactoring and commenting

[Callum McKenzie <callum spooky-possum org>]

On Sun, 2006-12-10 at 16:04 +1100, Robert Ancell wrote:
> Hi all,
> 
> I recently refactored part of Gnomine as trying to modify it for Bug
> #307245 was very difficult. Part of the refactoring included adding
> comments on some confusing sections (very little of the codebase seems
> to be commented). As I now know the gnotravex codebase quite well I
> plan to do some fairly heavy refactoring on it soon.(it is a 2000 line
> single file that is crying out to be split into two or three parts).
> 
> What is the Gnome Games community position on refactoring/commenting?
> I am particularly interested as I chose gnotravex as the first game to
> make changes to due to it's relative simplicity. However the code is
> quite complex and would potentially turn off future coders and
> patchers. I think lowering the bar to new developers is a timeworthy
> task.

I won't comment on what is official policy, but I will give a couple of
bits of advice from my experience with the games:

Refactoring is, ultimately, good. However, the gains may not be
commensurate with the effort applied. I know that the effort required to
completely rewrite same-gnome was excessive even though the outcome was
good. Simpler stuff is more likely to be worth it, but in the end only
you can judge (and if you're like me you will go ahead anyway).

Refactoring code adds bugs. So merge code in as early in the release
cycle as possible. Most will be easy to fix - after all the structure is
cleaner, you still remember what the code does and most will be typos.
Unfortunately, the worst case is when you miss something important that
was obscure in the original code.

When commenting code don't be too respectful to previous comments. They
age as badly as the code does (and some of it very old). If it doesn't
make sense to you it probably won't make sense to anyone else.

Good luck.

 - Callum