Encouraging good comments Which language ?

classic Classic list List threaded Threaded
28 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Encouraging good comments Which language ?

YES NOPE9
If this question has been addressed previously.... please point me in the correct direction.

What language is most likely to encourage good commenting ( What is being done and why ? )  and make the code easier to support by a future maintainer  ?
Or is this just not something that is influenced by the language......

99guspuppet           99comments
Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Rob Kendrick-2
On Sun, Jan 29, 2012 at 05:57:42PM -0700, YES NOPE9 wrote:
> If this question has been addressed previously.... please point me in the correct direction.
>
> What language is most likely to encourage good commenting ( What is being done and why ? )  and make the code easier to support by a future maintainer  ?
> Or is this just not something that is influenced by the language......

If I'm expected to support the code, it would have to be English.
Otherwise, perhaps Lojban? :)

B.

Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Rena
On Sun, Jan 29, 2012 at 18:20, Rob Kendrick <[hidden email]> wrote:

> On Sun, Jan 29, 2012 at 05:57:42PM -0700, YES NOPE9 wrote:
>> If this question has been addressed previously.... please point me in the correct direction.
>>
>> What language is most likely to encourage good commenting ( What is being done and why ? )  and make the code easier to support by a future maintainer  ?
>> Or is this just not something that is influenced by the language......
>
> If I'm expected to support the code, it would have to be English.
> Otherwise, perhaps Lojban? :)
>
> B.
>

Good comments explain what the code is doing, and why - not how.
(That's what the code is for.) You should be able to understand the
code months later when all those clever tricks are no longer fresh in
your mind.

Or did you mean mailing list comments?

--
Sent from my toaster.

Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Patrick Rapin
In reply to this post by YES NOPE9
> What language is most likely to encourage good commenting ( What is being done and why ? )  and make the code easier to support by a future maintainer  ?
> Or is this just not something that is influenced by the language......

Personally, I only write extensive comments in Assembly language, and
for complex Perl regular expressions...
Because otherwise, I cannot read back my own code.
IMHO, Lua does not encourage good commenting, because the language is
already quite clean.
It is easier to maintain uncommented Lua code than a well commented
one in assembly language !

Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Rena
On Mon, Jan 30, 2012 at 00:40, Patrick Rapin <[hidden email]> wrote:

>> What language is most likely to encourage good commenting ( What is being done and why ? )  and make the code easier to support by a future maintainer  ?
>> Or is this just not something that is influenced by the language......
>
> Personally, I only write extensive comments in Assembly language, and
> for complex Perl regular expressions...
> Because otherwise, I cannot read back my own code.
> IMHO, Lua does not encourage good commenting, because the language is
> already quite clean.
> It is easier to maintain uncommented Lua code than a well commented
> one in assembly language !
>

True, ideally your code would be so clear and readable that comments
aren't even necessary, but I think that may never be a reality until
computers can understand natural language...

--
Sent from my toaster.

Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Dirk Laurie-2
In reply to this post by Patrick Rapin
Op 30 januari 2012 09:40 schreef Patrick Rapin <[hidden email]> het volgende:

IMHO, Lua does not encourage good commenting, because the language is
already quite clean.

 
Lua has no need of tautological comments, true.   Except if the recurrent baying for syntax like `x+=++y` eventually succeeds, which is unlikely. 

But if you like to comment properly, i.e. to explain the strategy rather than the tactics of your code, then Lua is helpful.

-- A standard construction for a comment that can start after code and goes to the end of the line.
--[[
An easy construction for a comment that spans many lines and can contain arbitrary characters.

Also useful for temporarily disabling code.
--]]
---[[ An optimally quick way to enable the code again.

-- Lua's support for literate programming tools is nonexistent (no line pragmas) and therefore you have no option but to use comments.  :-Q



Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

GrayFace
In reply to this post by YES NOPE9
LuaDOC is a good way to encourage comments.

--
Best regards,
Sergey Rozhenko                 mailto:[hidden email]


Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Axel Kittenberger
In reply to this post by Rena
> Good comments explain what the code is doing, and why - not how.
> (That's what the code is for.) You should be able to understand the
> code months later when all those clever tricks are no longer fresh in
> your mind.

This!

I have a grudge against the usual coders arguments "good code does not
need to be commented, because it explains itself", pah! A single
*english* line per function/file that explains what the function does
or what the collection in this file is for makes diving into a source
base so much easier.

About YES NOPE9 question. It depends on the coder not on the language,
all language are equal to this, only difference maybe how easy you can
generate other documents out of the inline comments.

Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Petite Abeille

On Jan 30, 2012, at 10:14 AM, Axel Kittenberger wrote:

> I have a grudge against the usual coders arguments "good code does not
> need to be commented, because it explains itself", pah! A single
> *english* line per function/file that explains what the function does
> or what the collection in this file is for makes diving into a source
> base so much easier.

Perhaps this is more a question of cost vs. benefit:

(1) Who are the comments intended for?
(2) Who benefit from them?
(3) Who pay the cost of writing and maintaining them?

Not really a technical issue, more of a social/organization one.

This question about "comments" and who should pay for them, vs. who benefits from them, reminds me of Cory Doctorow rant about metadata:

Metacrap: Putting the torch to seven straw-men of the meta-utopia
http://www.well.com/~doctorow/metacrap.htm

Replace "metadata" with "code comment" and see how it works out for you :D

Commentcrap: Putting the torch to seven straw-men of the comment-utopia




Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Axel Kittenberger
> (2) Who benefit from them?
> (3) Who pay the cost of writing and maintaining them?

The magic line is: Little cost, great benefit. Come'on are you telling
me, writing a single line of english per function is going to take you
that much longer for a project? How long does it take you to write an
average sized function, including debugging all bugs etc. vs. the time
it takes to write a single line of english. Also compare how long does
it take for someone to understand the function with and without the
line.


> Metacrap: Putting the torch to seven straw-men of the meta-utopia
> http://www.well.com/~doctorow/metacrap.htm
> Replace "metadata" with "code comment" and see how it works out for you :D

Sorry, but this analogy is very faulty:
#1 People lie  -- So you are fearing of coders lieing in the comments?
You got serious problems elsewhere.
#2 People are lazy -- Yes, so what? At least say, I'm too lazy to help
you understand the code. Be at least honest about it, instead of
coming up this usual "good code explains itself" excuse crap.
#3 People are stupid --- If your coder is stupid, you got serious
problems elsewhere.
#4 Mission: Impossible -- know thyself --- There is no weighting in
comments. So several coders have a different style in commenting so
what?
#5 Schemas aren't neutral -- Who required comments to be "neutral".
Dude. What seriously, this is one of the badest analogies made.
#6 Metrics influence results -- For comments? Please, yes they *do*
make a difference.
#7 There is more than one way to describe something --- Who cares?
Nobody said one function would only have one possible english language
to describe its function.

Sorry, please overthing your analogy. Nothing of it applies.
"Metacrap" is about the problems of hugh distributed databases, with
an undefined and uncontrolled number of people contributing some of
the malicious. This does not apply in any way to any sane coding
project.

Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Petite Abeille

On Jan 30, 2012, at 3:27 PM, Axel Kittenberger wrote:

>> Replace "metadata" with "code comment" and see how it works out for you :D
>
> Sorry, but this analogy is very faulty:

I guess this, hmmm, mixed metaphor didn't quite work for you then. Oh, well...

Still... I would argue that, in general, there is a gross misalignment in incentives between who is expected to comment code and who benefits from it.

But, as with many other things, we can agree to disagree.


Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Axel Kittenberger
> Still... I would argue that, in general, there is a gross misalignment in incentives between who is expected to comment code and who benefits from it.

This formulation on the other hand I agree with. I wouldn't call it
"gross", but the difference in persons between the commenter and the
beneficted is the reason comments are missing. Its the classical of
the economic "dilemma", albeit objectively the total utility would be
far greater with comments, since they are little investment to the one
but great benefit of the other, it might not happen, because of
egoism. But at least lets be honest about that one, "I'm egoistic and
for me the 2% more work I'd have to invest to make your bricolage 50%
more easier is not worth it me, because I'm lazy", instead of this big
"good code comments itself" bullshit, that coders learned insight out
as lame excuse.

Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Jorge Visca
In reply to this post by Axel Kittenberger
On lun, 2012-01-30 at 15:27 +0100, Axel Kittenberger wrote:
> The magic line is: Little cost, great benefit. Come'on are you telling
> me, writing a single line of english per function is going to take you
> that much longer for a project?

Oh, it does when that comment makes you realize the function is ugly and
makes no sense, and you better refactor everything.

Oh.



Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Petite Abeille
In reply to this post by Axel Kittenberger

On Jan 30, 2012, at 4:36 PM, Axel Kittenberger wrote:

> albeit objectively the total utility would be
> far greater with comments, since they are little investment to the one
> but great benefit of the other

If that's the case, then, the one benefiting from the comments should take care of writing, using and maintaining them. You know, for the greater good. In which case everybody incentives will be aligned: clear code leads to meaningful comment which brings good documentation, demonstrating clarity of thought and purpose, etc, etc, ...  

Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Axel Kittenberger
> If that's the case, then, the one benefiting from the comments should take care of writing, using and maintaining them. You know, for the greater good. In which case everybody incentives will be aligned: clear code leads to meaningful comment which brings good documentation, demonstrating clarity of thought and purpose, etc, etc, ...

That makes no sense again. The beneficiary is not able to write the
comment, and once he went through the cost of parsing the code line be
line, s/he does no longer gain from it.

Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Paul Hudson-2
Is this anything to do with Lua any more, or another one of the entertaining but slightly frustrating off topic discssions covered extensively in other forums that the lua-list seems particularly susceptible to?

Paul
/And is this a rhetorical question?

Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Petite Abeille
In reply to this post by Axel Kittenberger

On Jan 30, 2012, at 5:28 PM, Axel Kittenberger wrote:

> That makes no sense again.

This happens.

> The beneficiary is not able to write the
> comment,

Why not? Is there a problem with the code?

> and once he went through the cost of parsing the code line be
> line, s/he does no longer gain from it.

Why not? Shouldn't the beneficiary write down these findings at that point? Perhaps even provide a bit of feedback?


Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

KHMan
In reply to this post by Paul Hudson-2
On 1/31/2012 12:33 AM, Paul Hudson wrote:
> Is this anything to do with Lua any more, or another one of the
> entertaining but slightly frustrating off topic discssions covered
> extensively in other forums that the lua-list seems
> particularly susceptible to?
>
> Paul
> /And is this a rhetorical question?

Consider instead that there are a lot of list members who aren't
participating in these kind of discussions... *yawn* :-P

--
Cheers,
Kein-Hong Man (esq.)
Kuala Lumpur, Malaysia

Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Max de Bayser
In reply to this post by Petite Abeille
> Why not? Shouldn't the beneficiary write down these findings at that point? Perhaps even provide a bit of feedback?

Now that is an interesting idea. Documentation tools such as
luadoc/javadoc/doxygen
could be integrated with some sort of CMS to allow users to post comments.

I've recently been working with a huge open-source code base. Ok, they
actually use
doxygen, but it's mostly stuff like:

//! Does foo
Bar doFoo();

which isn't terribly useful. At some time I managed to understand how
the code worked
but that's just me. The next person trying to use the code will have
to go through the same
painful process. If I could add comments to the documentation every
time I have an "Aha!"
moment, it could be helpful to others

Reply | Threaded
Open this post in threaded view
|

Re: Encouraging good comments Which language ?

Petite Abeille

On Jan 30, 2012, at 6:19 PM, Max de Bayser wrote:

>> Why not? Shouldn't the beneficiary write down these findings at that point? Perhaps even provide a bit of feedback?
>
> Now that is an interesting idea. Documentation tools such as
> luadoc/javadoc/doxygen
> could be integrated with some sort of CMS to allow users to post comments.

http://lua-users.org/wiki/LuaAnnotate


12