Sign in Join

Live chat for Free Pascal, Lazarus, Delphi and every Pascal programmer.

Mailing lists / lazarus / 2003-02

Comments

5 messages · 4 people ·

Reply by email Subscribe to this list Your subscription

Read-only archive. Use j and k to move between messages.

Unknown author

Hello,

I'm sure there is the "WHY" poeple do not use comments. I do not know it and I am curious.
I found writing comments a useful habit. It is useful even if I want to modify my source later.

When I found a bug or a missing feature I'm not forced to write a bug report or wish, I'm allowed to report a bug solution too. Or add a feature. It is why the source is present and licence encourage doing this. Ok, but when I get the source I see a lot of interesting name. Or I see an algorithm and quite complex. I wonder what it does. And at last I say fuck and pass the work to its maintainer. If it is good to him/her... but it is slower progress.
In python there is .__doc__. There exists javadoc and so on. I think it is a good thing that lazarus is documented. Some fancy tool is capable to do this if the source have comments in the right way.
And so on, and so on.

So I'm the one who is uninformed. Tell me what is the "WHY"?

Joe

Reply by email

Shane Miller

I know from personal experience with Lazarus that when we started the project (many years ago) we were 3 developers coding and we wanted to get something up and running ASAP to see if our ideas were sound.

In general, I agree with Vincent that comments are often unneeded for a lot of procedures and would simply get in the way. However, whenever there are confusing algorithms they should be commented. At least one comment to explain a group of procedures would have been a good idea.

Shane

Earlier message 55 lines
-----Original Message----- From: Vincent Snijders Sent: Wednesday, February 26, 2003 8:41 AM To: Subject: RE: [lazarus] Comments > Van: Ian Bell > On Wednesday 26 Feb 2003 2:38 am, wrote: > > Hello, > > > > I'm sure there is the "WHY" poeple do not use comments. I do not know it > > and I am curious. > > Probably laziness. Many programmers are so keen to make progress they > 'forget' to comment thier code. i think this is a mistake in any > code and > especially open source code where the idea is others can look at > the code to > undestand how it works and either improve it or derive other code from it. > > Arguments like 'the code is self documenting' just do not wash. > > Ian Maybe writing good, useful comments is more difficult than writing code... At least most of the times, when I write a piece of code I don't know what to add to it in comments, except the plain obvious like: function TUnitList.GetItem(Index: integer): TUnit; The function GetItem returns a Unit from the UnitList. It has one parameter Index, which is the index of the unit in the list of the returned unit. Also it is not immediately clear if some comment is good, usefull. Code is checked by the compiler and by tests to see if it works. For comments there is no such simple checking mechanism. Regards, Vincent Snijders. _________________________________________________________________ To unsubscribe: mail with "unsubscribe" as the Subject archives at http://www.lazarus.freepascal.org/mailarchives CONFIDENTIALITY NOTICE: This e-mail message, including any attachments, is for the sole use of the intended recipient(s) and may contain confidential and privileged information. Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient, please contact the sender by reply e-mail and destroy all copies of the original message.

Reply by email

Unknown author
> I'm sure there is the "WHY" poeple do not use comments. I do not know it > and I am curious.

...

Arguments like 'the code is self documenting' just do not wash. Ian

--------
I mean when I read comments and function names I understand it.

Maybe writing good, useful comments is more difficult than writing code...

Ok, it is your why. (Just in case you really don't use.)

At least most of the times, when I write a piece of code I don't know what to add to it in comments, except the plain obvious like: function TUnitList.GetItem(Index: integer): TUnit; The function GetItem returns a Unit from the UnitList. It has one

parameter

Index, which is the index of the unit in the list of the returned unit.

Sure. It is obvious and the names tell all the story. It can happen TUnitList is not so obvious name (eg. an abbreviation). Or not only get an item. Like pop and push in a stack. Do not stuck in my example, please. The proc or func has side effects.

Also it is not immediately clear if some comment is good, usefull. Code is checked by the compiler and by tests to see if it works. For comments

there

is no such simple checking mechanism.

Well, if a person knows other people will read his code I don't think he will
write stupidity. He should know what his code does. Even if he has some mistake
it may better than no you will se this: 'I think there is
an inconsistency in comment and code here: ...'
And? There are other bugs too. :)
-------

In general, I agree with Vincent that comments are often unneeded for a lot of procedures and would simply get in the way. However, whenever there are confusing algorithms they should be commented. At least one comment to explain a group of procedures would have been a good idea.

I like it.

Joe

Reply by email

Vincent Snijders
to Ian Bell: Probably laziness. Many programmers are so keen to make progress they 'forget' to…
Show quoted text 17 lines
Van: Ian Bell On Wednesday 26 Feb 2003 2:38 am, wrote: > Hello, > > I'm sure there is the "WHY" poeple do not use comments. I do not know it > and I am curious. Probably laziness. Many programmers are so keen to make progress they 'forget' to comment thier code. i think this is a mistake in any code and especially open source code where the idea is others can look at the code to undestand how it works and either improve it or derive other code from it. Arguments like 'the code is self documenting' just do not wash. Ian

Maybe writing good, useful comments is more difficult than writing code...

At least most of the times, when I write a piece of code I don't know what to add to it in comments, except the plain obvious like: function TUnitList.GetItem(Index: integer): TUnit; The function GetItem returns a Unit from the UnitList. It has one parameter Index, which is the index of the unit in the list of the returned unit.

Also it is not immediately clear if some comment is good, usefull. Code is checked by the compiler and by tests to see if it works. For comments there is no such simple checking mechanism.

Regards,
Vincent Snijders.

Reply by email

Ian Bell
to Unknown author: I'm sure there is the "WHY" poeple do not use comments. I do not know it and I am curious.
Hello, I'm sure there is the "WHY" poeple do not use comments. I do not know it and I am curious.

Probably laziness. Many programmers are so keen to make progress they 'forget' to comment thier code. i think this is a mistake in any code and especially open source code where the idea is others can look at the code to undestand how it works and either improve it or derive other code from it.

Arguments like 'the code is self documenting' just do not wash.

Ian

Reply by email