Is this a good code documentation practice?

Question

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.

Answer 1

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.

Answer 2

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

Answer 3

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.

Answer 4

You might want to use a format from which a tool can generate documentation (e.g. as HTML pages) automatically.

For Java code, use Javadoc.

C# uses <summary> XML tags which can be converted by e.g. Sandcastle.

---

It is important to state what a piece of code wants to achieve. "The code is the documentation" breaks down if the code actually works different from the intended purpose, due to bugs. Still, you should use meaningful names for variables etc.

Classes should state which concern they are covering.

Methods should state what they intent do achieve. Nice to have are the semantics of their parameters and return value, and what happens in an error case.

Unit test methods should describe the szenario they are testing and the expected outcome.

Use comments in the body of methods sparsely. Do not explain steps that can be made obvious if meaningful names are used. I use comments in the body mainly to group blocks of code that need many lines to perform a certain step. C# #region is very useful for this.

---

If you find that you can't provide a high-level description of a class or method in a single line, this could indicate that you did not separate your concerns sufficiently.

As others noted, author information, versions, changes etc. should be pulled from source control. Might be a good idea to also put this into a README file central to the project.