3

I'm working on 2 projects projA and projB, and both projects are maintenance projects. For projA there are 3 programmers and for projB there are 2 programmers. In each case all are working on separate points.

As code documentation is very important, can you tell me which one is the better practice?

Examples:

  {Author : lee    -verion 1.7    -date 30 dec  -asked by someGuy  -decription: to antialiase a line}   
  procedure antiAlias(thisline);
  begin
     //do the anti aliasing...
   end;

or

   {*123}
  unit testone;
..
..
..

    procedure antiAlias(thisline);
  begin
     //do the anti aliasing...
   end;
..
..

 end. //end of the unit..

{*123}
  {Author : lee    -verion 1.7    -date 30 dec  -asked by someGuy  -decription: to antialiase a line}

the {*123} represent the point I have done for the particular unit. So the next point {*124} will be at the end of the unit.

This is done (very rarely though) as the code looks clean without the commented part and lots of decription at the end.

8

I personally dislike both approaches. With the exception of the description (which ideally I'd have before the method i.e. the first example) the other details add unnecessary clutter to the code, this is what source control and commit logs are for.

  • +1 for the explanation ,ok and what you have to say the amount of decription for each point? – PresleyDias Jan 2 '12 at 5:25
6

Just comment what it does and why - things the programmer fixing the code needs to know and can't get from reading the code.

Who, where, when, etc they can get from the comments on the SVN/GIT/etc checkin

  • can you give an example refering to my procedure antiAlias(thisline); ?...it will be realy apprciated – PresleyDias Jan 2 '12 at 5:58
6

It is not neccessary to track revision history in code comments.

Documentation should start with meaningful entity names. Comments should expand on what the name and signature tells you. A method named "antiAlias" which takes a parameter "thisLine" does not need a comment explaining that it is "to antialiase a line", that much is obvious. It could be useful to explain what you mean by "antialias". If your environment supports a style of comments that shows up in inline help for the entity, such a comment documenting what a method does should use that. Comments documenting how the code works should apppear just before the code described.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.