Re: svn commit: rev 1624 - trunk/subversion/include trunk/subversion/clients/cmdline

[Greg Stein <gs...@lyra.org>]

On Wed, Apr 03, 2002 at 04:02:34PM -0600, sussman@tigris.org wrote:
>...
> * feedback.c (notify_added): rearrange comment.
>...
> +++ trunk/subversion/clients/cmdline/feedback.c	Wed Apr  3 16:02:34 2002
> @@ -42,8 +42,9 @@
>  static void 
>  notify_added (void *baton, const char *path)
>  {
> -  /* the pool (BATON) is typically the global pool; don't keep filling it */
>    struct notify_baton *nb = (struct notify_baton *) baton;
> +
> +  /* the pool (BATON) is typically the global pool; don't keep filling it */
>    apr_pool_t *subpool = svn_pool_create (nb->pool);

Okay. Now I will make some commentary on comments...

In general, I try to avoid a lot of spurious comments, and strive to make
the code clear. Where it is simply opaque, I definitely add them. If I
reread some previous code that I wrote and don't understand it right off the
bat, then I add comments. Of course, it does mean that what I write can
definitely be under-commented for most people.

At least for myself, it also partly stems from how I write the code. I
rarely stop-and-plan (and drop in comments describing the plan) because the
coding/planning pretty much just flow at typing speed.

I'd like to think that by avoiding comments-as-a-crutch, that I write
clearer code. Obviously debatable, tho :-)

But the real point that I want to make about comments: they fall out of
sync. The above was an example, and is *still* out of sync. An out-of-sync
comment is worse than no comment at all. It is misleading and can redirect
somebody down the wrong thought-path.

Just a few weeks ago, I saw a commit go into Apache which removed some code.
Right above that was a big warning comment that referred to the removed
stuff; when the code disappeared, that comment was absolutely awful. Next
person to see it would be all, "what the hell? um. what is it referring to.
[dig dig] dang. what is going on?" And the only way to realize that the
warning no longer applied was to dig through prior revisions in CVS.


I'm not suggesting we start stripping comments, but I also had to do a bit
of venting on not using comments properly and not keeping them in sync.
And to point out that comments can be just as dangerous as they can be
helpful.

Cheers,
-g

-- 
Greg Stein, http://www.lyra.org/

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org