Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
1  
See also: programmers.stackexchange.com/questions/126230/… –  MainMa Dec 30 '11 at 18:10
1  
+1 for actually caring to document, even if, as the answers explain and I agree, both examples are bad. Keep worrying about this stuff - it's critical to this business. –  Ross Patterson Dec 31 '11 at 0:20
1  
I would VERY highly recommend this book to you: The Art of Readable Code. It is readable, practical, and speaks with great wisdom to situations just like yours. –  TehShrike Jan 1 '12 at 20:22
add comment

3 Answers

up vote 8 down vote accepted

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.

share|improve this answer
    
+1 for the explanation ,ok and what you have to say the amount of decription for each point? –  cod3r Jan 2 '12 at 5:25
add comment

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

share|improve this answer
    
can you give an example refering to my procedure antiAlias(thisline); ?...it will be realy apprciated –  cod3r Jan 2 '12 at 5:58
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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