[Tfug] Developer question

[Bexley Hall]

--- Rich <r-lists at studiosprocket.com> wrote:

> On Jul 6, 2007, at 5:12 pm, Robert Hunter wrote:
> 
> > The difficulty, as I see it, is that you are
> trying to prevent an  
> > intent error using syntactic mechanisms.  Strictly
> speaking, it is  
> > impossible to do this, although you may be able to
> make it  
> > blindingly obvious how your code should be handled
> by other  
> > developers.
> Which begs the question, what's wrong with comments?

There's absolutely *nothing* "wrong" with comments
(assuming they agree with the code and actually
"add value" -- instead of just taking up space).

The problem with RELYING on comments is you are
assuming the next developer (maintainer?) will
*see* the comments and act accordingly.

In my experience, when dealing with anything other
than a "trivial" piece of code (i.e., something in
the > 30KLoC size), there is rarely a document
(up-to-date!) that reflects how the code is
"organized", what each "module" does, etc.  (note
not all "programs" begin with "main.c").

So, when told to make a particular change, there is
often a fishing expedition wherein the developer
thrashes around through the code *hoping* to
stumble on the piece of code he/she *thinks* is
pertinent.

Building on the previous example...

"I have to add support for the color 'Mauve'.
I know the *existing* colors are 'Red', 'Green',
etc.  So, I'll grep(1) the sources for these
strings....  Ah!  Here we go!  Looks like I
just add an entry to colornames[] for ''Mauve''
and that should be it!"

OK, so put comments around the colornames[]
definition, right?  And, those comments would have
to explicitly direct the individual to seek out
the color_t enum (you wouldn't want to mention
a file name since that might change in the future
and now you'd have introduced a maintenance issue
in your comments that will unlikely be serviced).

But, you would also have to put complementary 
comments with the color_t enum directing the
developer to the colorname[] table -- with similar
constraints.  And, any *other* things that are
interrelated.

In my experience, these things just get overlooked.
If the code *seems* like it works, the developer
*assumes* that it works!  Which means you need
a comprehensive set of regression tests if you
want to ENSURE that it works.  But, you then have
to assume the developer will update those tests
to reflect the addition he just made (since those
tests undoubtedly do NOT test for "Mauve" -- as it
didn't exist when the test were crafted, etc.).

<shrug>  Chalk it up to personal "style" but I like
forcing the developer to pay attention to things
that are apt to be easily brushed aside (adding a
new color *seems* like it should be easy so why
would the maintainer go out of his way *looking*
for "issues"?).

Of course, my application is considerably more
involved than the example suggests.  And, there
are a lot of dragons lurking that could easily
wreak havoc on the code in ways that would be
difficult for the unwary to troubleshoot
(e.g., keeping track of binary points, reordering
operations to safeguard against numerical overflow,
making sure correct data types are used to preserve
the accuracy of the algorithms, etc.).

Force an error and, hopefully, you force the developer
to look more carefully at what he is doing -- i.e.,
"my predecessor went OUT OF HIS WAY to force this
error so it *must* be important... *why*??"

<shrug>
--don


       
____________________________________________________________________________________
Be a better Globetrotter. Get better travel answers from someone who knows. Yahoo! Answers - Check it out.
http://answers.yahoo.com/dir/?link=list&sid=396545469