Some more thoughts...
Also remember that some developers perform many checkins to complete one
thread...
i.e. A developer might perform 10 checkins over a 2 week period to fix one
bug..
so...:
1)
I usually comment like this in my code (by this I mean "in" the code where
I code it:
###################################################################
#I am doing something very tricky or not so obvious so I am block
commenting #
# it so that other know what I am doing even though my code should be
self #
# commenting because I'm that good ;) This is to fix bug
#152. #
###################################################################
for cow in barn
milk_cow(cow);
... some tricky and complicated stuff ;
done
...
...
...
###################################################################
#I Some more tricky yada yada
yada.............. #
# explained in detail b/c it is tricky..... To fix bug
#152 #
###################################################################
for cow in barn
if (milk_cow(cow) == SOUR)
then
... some tricky and complicated stuff ;
else
... more tricky stuff
done
2)
Then at the top of the file I might place in the history. I do this only
once when the bug is fixed (even if it takes me many checkins to fix the
problem):
xx/xx/xxxx cclarke - fixed Bug#153
but in the checkin comment(s) I might put :
Created milk_cow for bug 152...
Called milk_cow for bug 152...
Added another call to milk_cow for 152...
Performed final error checkin ... to complete fix for #152
In this case there were 4 checkins of this file...
The tricky code part is commented in the code...
Each version is commented as per it's differences for its predecessor....
The internal history is updated just the one time (when the bug is fixed)..
Just my way... others are right of course.
-Charles
At 11:42 AM 1/10/00 -0800, Marilyn Sander wrote:
>Yeah, I agree that if the comments don't say anything more
>useful than that bug nnnnn was fixed, it's useless to replicate
>that information in both the metadata and the code. I was
>remembering cases where the engineer was being very wordy
>in explaining some subtleties in the code that he had spent
>hours to work out and understand. It is hugely helpful to
>have such comments go into the bug report and the code, but less
>so to have them in the metadata.
>
>Come to think of it, how have you dealt with this before?
>I mean, you have an interface to a bug-tracking tool integrated
>with the source code control system. You want the meaningful
>comments to go into the bug database and into the source code,
>but don't really want a treatise on source code logic to be
>saved in the metadata. What has happened here is that the
>wordy comments go into the metadata and the bug database, but
>never make it into the source code. Would you consider that
>preferable?
>
>--Marilyn Sander
>
>
>| X-Sender: abs_info@mail.mindspring.com
>| Date: Mon, 10 Jan 2000 14:28:07 -0500
>| To: Marilyn Sander <marilyn@hal.com>, cciug@Rational.Com
>| From: "A Better Solution, Inc." <cciug@abs-consulting.com>
>| Subject: Re: [cciug] Writing the comment in the source file
>| Mime-Version: 1.0
>| X-Majordomo-Taboo: cciug
>|
>| Marilyn,
>| I don't consider 200 lines of comments for 25 code lines bad in itself. I
>| only consider it bad if those lines "already" exist as metadata... The
>| comments that engineers place in code (normal code commenting) is good. But
>| the change summary to be placed at the top of the file can make source size
>| HUGE. I have seen data files where the data does not change in size, but
>| the comments were exhausting...
>| So now come file where the source is small but constantly changing but not
>| growing has the comment in the code where it happened (OK)
>| Has a summary at the top of the code AND has a summary in CC
>| metadata... (it is the duplicity of the cleartool ci comment ALWAYS being
>| duplicated in the file that I think might be overkill .. as the each ci
>| comment is stored once in the database and now forever in each version of
>| the file from that point on.
>| . i.e.
>|
>| (in the file)
>| ##################
>| # History
>| ###################
>| 10/2/99 - engineer xxx - change the yaya data to #232322 to fix bug 123
>| 10/1/99 - engineer yyy - changed the uzuz data to #44343 to fix my problem..
>| .....(more and more)
>| 9/2/99 - engineer xxx - change the yaya data to #236322 to fix bug 101
>| 9/1/99 - engineer yyy - changed the uzuz data to #47343 to fix my problem..
>| ..(more and more)
>| 10/2/98 - engineer xxx - change the yaya data to #242322 to fix bug 99
>| 10/1/98 - engineer yyy - changed the uzuz data to #24343 to fix my problem..
>|
>| #############
>| Actual data
>| ##############
>| # Changed yaya to 232322 for bug 123
>| ####################################
>| yaya=232322
>| ################################
>| #Change uzuz to 44343 to fix my problem
>| ####################################
>| uzuz=44343
>|
>| then when you do cleartool desc datafile you still get the checkin in
>| comment that is exactly what is in the summary above..
>|
>|
>| There are still needs for this.. I just to suggest it often without letting
>| them know exactly the duplicity they are requesting...
>| -Hope this helps..
>| -Charles
>|
>|
>| At 10:58 AM 1/10/00 -0800, Marilyn Sander wrote:
>| >But what's wrong with 200 lines of comments to document 25 lines
>| >of changes? When I used to maintain code, I certainly appreciated
>| >my "wordy" predecessors who explained what they were doing to the
>| >code and why. We should remember that the source control system
>| >exists as an aid to good engineering, not as an end in itself.
>| >
>| >--Marilyn Sander
>| >
>| >| X-Sender: abs_info@mail.mindspring.com
>| >| Date: Mon, 10 Jan 2000 10:15:34 -0500
>| >| To: "jangareddi, ramesh" <jangareddi_ramesh@emc.com>, "'cciug'"
>| ><cciug@Rational.Com>
>| >| From: "A Better Solution, Inc." <cciug@abs-consulting.com>
>| >| Subject: Re: [cciug] Writing the comment in the source file
>| >| Mime-Version: 1.0
>| >| X-Majordomo-Taboo: cciug
>| >|
>| >|
>| >| Jangareddi,
>| >|
>| >| I could do so and will if after this you still request it., but I feel
>| >| obligate to first talk you out of it...
>| >|
>| >| the checkin in comment is always available as metadata to you and easy to
>| >| view, but when you place checkin comments in the
>| >| code then you end up with large source files as some small files change
>| >| alot and some engineers are very "wordy".... imagine a often changed file
>| >| that has after a year of development 200 lines of comments at the top
>| >| commenting 25 lines of often changed code.. I have seen it...
>| >| You could limit the comment string , but that only slows the problem
>| >| down... You could only place in the last comment, but then a cleartool
>| >| describe on the file would be equivalent to this..
>| >|
>| >| It is possible that you have some really good reason to do this....
>perhaps
>| >| it was just mandated down to you from higher management, but again I must
>| >| stress that perhaps this is not what you "really" want to do ... If I am
>| >| wrong, or my cautions do not apply to your particular situation, then of
>| >| course I will share a trigger that performs this action.... (or very
>| >similar)..
>| >|
>| >| http://www.abs-consulting/abs_consulting_triggers.html
>| >|
>| >| has a trigger called MAKE_VERSION_ID.tgr ... it creates static data in
>| >| source code... you could change is very easily to do what your asking.. I
>| >| believe you could find the 2 lines that might need to change..
>| >| -
>| >| Hope this helps
>| >| -Charles
>| >|
>| >| --- VOB Corleone
>| >| "One day.. and this day may never come... I might ask you for a
>| >favor.."
>| >|
>| >| A Better Solution, Inc.
>| >| ----------------------------------------------------
>| >| Charles Clarke III ClearCase Consultant
>| >| A Better Solution, Inc. (770) 252-1500 x22 [phone]
>| >| 50 Springridge Ct.
>| >| Newnan, Ga. 30265 (770) 252-1501 [fax]
>| >| Email:
>| >| charles@abs-consulting.com
>| >|
>| >http://www.abs-consulting.com
>| >|
>| >|
>| >|
>| >| At 08:39 AM 1/10/00 -0500, jangareddi, ramesh wrote:
>| >|
>| >| >Hi cciug,
>| >| >
>| >| > I am looking for a way to write the ClearCase comment into the
>top
>| >| >of a source file, so if there is any trigger / method that some one is
>| >| >already implemented that would like to share, will be very helpful.
>| >| >
>| >| >Thanks a lot,
>| >| > - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
>| >| >
>| >| >
>| >| >
>| >| > http://clearcase.rational.com/cciug/mailing_list.html
>| >|
>| >| - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
>| >|
>| >|
>| >|
>| >| http://clearcase.rational.com/cciug/mailing_list.html
>| >
>| >-----------------------------------------------------------------------
>| >Marilyn E. Sander, CM Engineer marilyn@hal.com
>| >Fujitsu System Technologies (408)341-5590
>| >Division of HAL Computer Systems, 1315 Dell Avenue, Campbell, CA 95008
>| >-----------------------------------------------------------------------
>
>-----------------------------------------------------------------------
>Marilyn E. Sander, CM Engineer marilyn@hal.com
>Fujitsu System Technologies (408)341-5590
>Division of HAL Computer Systems, 1315 Dell Avenue, Campbell, CA 95008
>-----------------------------------------------------------------------
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
This archive was generated by hypermail 2b29 : Sun May 06 2001 - 00:22:22 EDT