Do I Need To duplicate comments in Every File?

Question

I have very similar code over multiple files in my project. If a client wanted some level of commented code, would I have to invest the time into duplicating the code for every file. I think it would simply be a waste of time. What would be the best/easiest way to provide comments to a client. (Refer them to a readme to show one file with the comments?) It's along the lines of URL's to point to and BOOL's to change.

For Clarification: I don't want to, nor do I think it would be a good idea to consolidate code to create a single place for settings. If I was building a desktop app or using PHP, I would create a config file. But this isn't a situation where that would be called for. Infact, it might actually be considered (from what I understand) a best-practice. I totally get that It's a good idea to eliminate duplicate code, but I don't even think there's an efficient and simple way to eliminate the duplicate base code. My question pertains how I should Comment for clients/dev's in these sort of situations*

Disclaimer: Next time, I'll start with comments rather than adding them in later.

Answer 1

If I understand you correctly, you are working with a framework that recommends a lot of very similar files, not repeating the logic, just structure - interface code that fits your classes into the framework.

In this case, take one, most-representative file and comment it richly. Then in each similar file, give a shortie synopsis:

  /* generic Controller for screen X. See @filename for general structure */

If the file has significant differences, mention them in the header, then comment them near the exceptional piece.

  /* special Controller for screen X. See @filename for general structure */
  /* exceptional behavior: function Y adds an event listener Z, in order to
   * handle the special behavior in case widget W receives new data. */

Answer 2

Have you considered fixing your code so all these almost similar places call a common routine and then put the desired comment in there?

Answer 3

Over commenting isn't very helpful I've found. If you have meaningful variable names and concentrate on writing clean logical code you shouldn't need to comment very heavily. Otherwise listen to Thorbjørn Ravn Andersen - his point is spot on. Don't repeat yourself, refactor your code to eliminate duplication.

Answer 4

It is favorable to comment each file, but if You have hundreds of them, it would be easier to add comments to the beginning of the file briefly describing what is it meant for.

If You have lots of similar files, then I suggest You automate the process by creating a small script.

Answer 5

Don't comment. If you change your code, you need to re-comment, it is contraproductive. Use self-explanatory naming instead, see example.

comment attitude, comments are almost esseintial

// ordinates of perpendicular triangle
var a,b;

// read ordinates
function input() {
  read(a);
  read(b);
}

// area of perpendicular triangle
function calculate() {
  return a*b/2;
}

naming attitude, comments are useless, all is self-explanatory

var ordinateA, ordinateB;

function readOrdinates() {
  read(ordinateA);
  read(ordinateB);
}

function perpendicularTriangleArea() {
  return a*b/2;
}

And do not confuse user manual with comments in code !

Answer 6

I know that this doesn't directly answer the question as posed, but if this is about "change stuff here to change how the software works, and this is the meaning of each variable" followed by "don't change anything after this point or you will break things" (as your example indicates), then you are probably better off separating the configuration parts into a single file, which can be commented and described however much you need, and which is included in all other files.

Other than that, I too agree with Thorbjørn Ravn Andersen.

Answer 7

You have two choices:

• comment the code in one place and in the other place use the same variable/parameter names and just insert a reference: "See the comments to routine Foo".
• provide a separate document and insert references to it (e.g. "See Section 4.3").

Code and comments are two separate streams of information and keeping them in sync is always a bit of a pain. We suffer this pain because of the benefits of having information about the context of the code/the contract of the code/etc, but it's still a pain. As others have said, writing clean readable code eliminates the need for part of comments. So it's a partial solution to a problem which doesn't really have a complete one.

Answer 8

If your customer wants that level of commenting and you are contractually bound to provide it then of course you will have to do the work, but I would say this is an expense not an investment for you.

---

However, depending on how you developed the software in the first place, there might be a shortcut, allowing you add the comments with less effort than you might think:

• If you use a version control system like mercurial which tracks copies, and you used it to create your duplicate code you files, may be able to use the facilities in your VCS to do some of this work for you.

For instance, if you created the duplicate code files by copying some common ancestor file using the VCS's copy command and then modifying the copied file, you may be able to update to the version where the common ancestor file was last changed, add the comments there and then merge those changes into the current version. With mercurial at least, the changes to the common ancestor file should be replicated through each of the copies of that file.

I have used this technique several times, usually when splitting a file containing multiple classes into multiple files with one class each. I was very impressed that mercurial was able to merge in pre-split bug fixes and apply them correctly to each of the post-split source files without manual intervention.

• If you didn't track copies like that, create patch files and apply them to each of your source files.

Patching mechanism have some 'give'. If you modify one of your source files to add the comments and then take a diff to the version in revision control, you end up with a patch file. This may apply quite cleanly to many of your other source files.

Either of these options could cut down on the work required quite significantly.