Comments on: Spot-welding Code: Tips for Maintaining Consistency

By: GEORGE

GEORGE — Tue, 03 Jun 2008 04:10:22 +0000

Is a welding procedure qualfication required as per any international codes, if yes then which code/standard is this..its an offshore job

By: J.T. Wenting

J.T. Wenting — Mon, 06 Aug 2007 06:34:38 +0000

Code littered with comments about who changed what and where (often accompanied by commented out lines of code to show what was there before if things were removed or changed rather than added) make code harder to read.
Not so bad when it’s a few spot changes here and there but over time such changes tend to pile up to the point where every single line has been changed multiple times, leading to maybe a dozen lines of change comments for each line of code.
I’ve seen it happen, the situation had become unworkable.
We agreed to cut out ALL those change comments, but someone higher up decided that wasn’t good. We were instead to leave the change comments related to the last 2 major releases in place.
So now we had less comments but a lot more bookkeeping as we had to constantly check when encountering a change comment (did I tell you this had to be done for the entire file whenever we changed a file?) whether it should be deleted or not.
How old was it? What version did that correspond to? Was that more than 2 major versions ago or not?

Better to rely on version control for such things (everything was also in version control, with mandatory change history also in the header of each file as well as version control checkin comments).
You can always leave a little remark stating what something does if it appears weird but is a necessary construct to make something work.

By: Dennis B

Dennis B — Fri, 03 Aug 2007 14:29:52 +0000

I agree that version control systems have improved, and everyone should be using them. And yes, to an extent, they can supplant leaving “kilroy was here” notes behind. That is provided developers actually enter useful checkin comments.

However, when I am reading source code and I see a change note, I have no need to look any further. I find that very convenient. In my opinion, the locality of reference outweighs the inconvenience of cluttering the code.

The second issue is with branching and version control. To my knowledge, there is still only one VC system that tracks branch merge points (Clearcase). The most popular open source VC systems, CVS and Subversion, while they have good branching capabilities, do not track merge points.

Why is this a problem? Because when I use version control (the annotate command) to track down a line of code to a revision number, 75% of the time, it points to a checkin containing the comment “merge branch XXX to trunk”. Then I have to try again to find the *real* change on that branch (usually a bug-fixing branch) and see who is responsible.

Also, most annotate commands do not help you find deleted code at all. You have to do a binary search diffing previous versions of the code until you can figure out when those critical lines disappeared. And unless you are extremely familiar with the code, how do you know those lines ever were there in the first place? All you know is that it doesn’t do something that it used to do.

Now, if a development group wants the best of both worlds, they should use SlickEdit 2007’s code annotation tools. With it, you can leave sticky notes all over the place without cluttering the code. It would be great if version control systems integrated this concept, so you could annotate individual changes with checkin comments, maintaining locality of reference, and making the annotations persistent with your source base. Until then, keep looking for my little notes

// DJB – 08-02-2007
// broke something that worked before

By: John Hurst

John Hurst — Thu, 02 Aug 2007 21:37:02 +0000

Good post.

I agree with the comment above about notes. We’ve got good version control practices now, and it allows us to be very aggressive with keeping code clean when it undergoes change. We don’t comment out code we’re getting rid of — we delete it. Someone can find it in VCS if he needs it. I put notes in for things that still need to be done (i.e. TODOs), not for things that have been done.

With regard to your comment about beautification: If I do make changes to “beautify” a file, or any similar non-functional change, I make sure I commit it in a separate change set from functional changes. For the reason you give — otherwise it’s too hard to see the functional changes amongst all the formatting changes.

Regards

John Hurst

By: Alan Shutko

Alan Shutko — Thu, 02 Aug 2007 18:29:52 +0000

I agree with most of this, but I disagree with your last suggestion. Don’t leave a note. If you do, the code will eventually be overshadowed by notes and it’ll be impossible to figure out which notes are still valid and which are historical.

Your version control system will be able to keep track of historical information. Use it. If you aren’t using one yet, start NOW.