[prev] [thread] [next] [lurker] [Date index for 2003/10/23]
On Thursday, October 23, 2003, at 12:34 pm, Mark Fowler wrote:
> On Wed, 22 Oct 2003, Piers Cawley wrote:
>
>> Why thank you. Generally my gut feeling is that every time I think
>> "Maybe I should add a comment here?" I'd be better off working out
>> what it is about the code that is hard to understand and rewriting it
>> so it's clear.
>
> This isn't always going to work. For example:
>
> sub delete {
> my $self = shift;
> my $obj_or_oid = shift;
>
> my $oid = ref($obj_or_oid) ? $obj_or_oid->PIXIE::oid : $obj_or_oid;
> $self->cache_delete($oid);
> $self->store->remove_from_store($oid);
> }
>
> This is perfectly clear up until we get to the bit we're deleting from
> the
> cache. It needs a comment to say *why* we have to delete from the
> cache.
> It's not the code isn't readable, it's that the reasoning behind the
> things hasn't been exposed.
I see where you're coming from, but in this case I disagree - it's
fairly obvious that we're maintaining a cache here, and that we should
delete from the cache when we delete from the store. This is the kind
of thing that should be covered in a design doc. Comments should be
reserved for explaining things that aren't so obvious like complicated
regexps.
Still, it can be bloody useful to comment while you figure out somebody
else's code. I tend to refactor - forces me to read things. I don't
want to stop you from doing what you like, but the coding style of this
project does not include many comments, so I'm just asking you to be
prepared to see some of your comments go away in patches.
-Steve
There's stuff above here
Generated at 13:56 on 01 Jul 2004 by mariachi 0.52