Is a standard comment before each procedure implementation useful?

[dummzeuch 1505]

While fixing some bugs in the code formatter I came across a functionality that I didn't know about:

procedure bla;
begin
end;

The formatter can insert a fixed comment above each procedure like this:

{ procedure }
procdure bla;
begin
end;

It does this only if the configuration option CommentFunction is set to True. It's False by default and there is no GUI way to set it, so I never noticed.

 

I think the way it currently works is pretty pointless, especially since the comment is hard coded as '{ procedure }' and is inserted above each procedure, function constructor and destructor. Even if there is already a different comment:

{ This is a comment }
procdure bla;
begin
end;

becomes

{ This is a comment }
{ procedure }
procdure bla;
begin
end;

Nobody needs that.

Would any other automatically created comment be more useful? I can't think of any, but maybe somebody else has an idea?

Currently I'd rather remove that functionality. I don't think a code formatter should add comments, it should simply format the source code that is there.

[Bill Meyer 337]

18 minutes ago, dummzeuch said:

Would any other automatically created comment be more useful? I can't think of any, but maybe somebody else has an idea?

Currently I'd rather remove that functionality. I don't think a code formatter should add comments, it should simply format the source code that is there.

I'd remove it. I have seen comments inserted as a matter of style,  and consider them noise. The worst, in my view, is the comment inserted after end.
procedure SomeOp;

begin

 

end; { SomeOp }

First because unless the routine is very long,  it is pointless, but more importantly because when you are removing code, the IDE will strip empty routines on save, and this trailing comment defeats that behavior.

Comments are useful where they explain the motivation, the reasons why non-obvious operations are performed. Boilerplate comments are worse than useless.

[Tom F 83]

11 hours ago, Bill Meyer said:

First because unless the routine is very long,  it is pointless,

Bill, not to start a flame war, but I love the  trailing comment on procedures:

 

procedure SomeOp;

begin

 

end; { SomeOp }

 

Why?  Because when I'm scrolling up from the bottom of a unit, when a procedure's end; statement comes into view, I can immediately identify the procedure without having to scroll up further.

As you say, the IDE does not strip empty procedures that have a comment like this. But, IMO, that's a small price to pay.

What does bug me is that when I use Shift_Ctrl-C, the IDE puts new methods between the end;  and the comment.  But even with that hassle, I still prefer the comment.

[FredS 138]

3 hours ago, Tom F said:

I can immediately identify the procedure

Agreed, used to be important.. but now that procedure navigation is done with tools like MMX that may no longer be required.
 

 

[A.M. Hoornweg 144]

Lately I've been switching to this style:

Function tMyClass.GetCustomerName(CustomerID:tGuid; OUT CustomerName:String):Integer;
{Retrieves the name of a customer. Exceptions:None; 
Result<>0 means error. See table ### for a list of possible errors}
Begin
   Result:=0;
  Try
   ....   read customer name    
  Except
    Result:=DetailedError;
  End;
End;

 

My reason for putting the comment inside the method is that the comments will fold out of view along with the method body when I use the folding feature of the IDE.  If I want to know what a method does exactly, I simply unfold that single method and the first thing I see is the comments. This way I can have the documentation where I prefer to have it (near the code) and keep it out of view most of the time.  I chose a light gray font for the comments to make them as un-obtrusive as possible.

 

An additional advantage of having the comments inside the method body is that it prevents tools such as MMX, Cnpack, GExperts etc from inadvertently separating the comment from the method it belongs to.  

 

 

[dummzeuch 1505]

18 minutes ago, A.M. Hoornweg said:

An additional advantage of having the comments inside the method body is that it prevents tools such as MMX, Cnpack, GExperts etc from inadvertently separating the comment from the method it belongs to.   

That's actually one change I made over Easter: The Formatter does no longer insert a blank line between a comment and the procedure it describes.

 

Are there any other experts in GExperts that do this?

[Fr0sT.Brutal 900]

I agree adding of such comments is not a formatter's task. It would be useful in more advanced form, like generating of documentation stub with all parameters and result.

[A.M. Hoornweg 144]

4 hours ago, dummzeuch said:

That's actually one change I made over Easter: The Formatter does no longer insert a blank line between a comment and the procedure it describes.

 

Are there any other experts in GExperts that do this?

I don't know. But I wouldn't rely on the absence of blank lines because there are several other code formatters around.

 

For example, I need to maintain some source code that must remain compatible with Delphi XE.  The built-in source code formatter of XE doesn't know how to format anonymous methods properly, so I use CNPack's formatter there.

[David Heffernan 2345]

> Is a standard comment before each procedure implementation useful?

 

No