About method comments

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

About method comments

Stephane Ducasse-3
Hi guys

From now on I will VETO the introduction of code where methods are not
commented.
I'm FEDUP FEDUP FEDUP to spend my time commenting methods that I do
not know and understand, juts because the original author thought that
this is obvious.

NOTHING IS OBVIOUS!!!!

So I will check if we can have a little process that systematically
reject code without enough method comments.

Pharo should grow and pharoers too.

Stef

PS: now you can comment that x said that method should be
self-explanatory. This is bullshit. I'm not asking for stupid
comments! I'm asking for respect for maintainers and other
programmers.

Reply | Threaded
Open this post in threaded view
|

Re: About method comments

Sven Van Caekenberghe-2


> On 9 Feb 2018, at 12:04, Stephane Ducasse <[hidden email]> wrote:
>
> Hi guys
>
> From now on I will VETO the introduction of code where methods are not
> commented.
> I'm FEDUP FEDUP FEDUP to spend my time commenting methods that I do
> not know and understand, juts because the original author thought that
> this is obvious.
>
> NOTHING IS OBVIOUS!!!!
>
> So I will check if we can have a little process that systematically
> reject code without enough method comments.
>
> Pharo should grow and pharoers too.
>
> Stef
>
> PS: now you can comment that x said that method should be
> self-explanatory. This is bullshit. I'm not asking for stupid
> comments! I'm asking for respect for maintainers and other
> programmers.

+100

The same goes for class comments too, duh.

One problem is that it is hard to check the quality/meaning of the comment.

"Comment later" would probably pass any check, as would "I am class XYZ".

Also,

name
  "Returns the receiver's name"
  ^ name

Would also pass a simple test, while it is quite useless.

I would say that any public, non-trivial methods need a comment.

So human judgement will be needed.

Sven


Reply | Threaded
Open this post in threaded view
|

R: About method comments

Lorenzo
In reply to this post by Stephane Ducasse-3
Great Stef!

Lorenzo

-----Messaggio originale-----
Da: Pharo-dev [mailto:[hidden email]] Per conto di Stephane Ducasse
Inviato: venerdì 9 febbraio 2018 12:04
A: Pharo Development List
Oggetto: [Pharo-dev] About method comments

Hi guys

From now on I will VETO the introduction of code where methods are not commented.
I'm FEDUP FEDUP FEDUP to spend my time commenting methods that I do not know and understand, juts because the original author thought that this is obvious.

NOTHING IS OBVIOUS!!!!

So I will check if we can have a little process that systematically reject code without enough method comments.

Pharo should grow and pharoers too.

Stef

PS: now you can comment that x said that method should be self-explanatory. This is bullshit. I'm not asking for stupid comments! I'm asking for respect for maintainers and other programmers.


Reply | Threaded
Open this post in threaded view
|

Re: About method comments

NorbertHartl
In reply to this post by Sven Van Caekenberghe-2
One more reason to do reviews. Now that it is super easy with iceberg there is less reason to do so.

Norbert

> Am 09.02.2018 um 12:10 schrieb Sven Van Caekenberghe <[hidden email]>:
>
>
>
>> On 9 Feb 2018, at 12:04, Stephane Ducasse <[hidden email]> wrote:
>>
>> Hi guys
>>
>> From now on I will VETO the introduction of code where methods are not
>> commented.
>> I'm FEDUP FEDUP FEDUP to spend my time commenting methods that I do
>> not know and understand, juts because the original author thought that
>> this is obvious.
>>
>> NOTHING IS OBVIOUS!!!!
>>
>> So I will check if we can have a little process that systematically
>> reject code without enough method comments.
>>
>> Pharo should grow and pharoers too.
>>
>> Stef
>>
>> PS: now you can comment that x said that method should be
>> self-explanatory. This is bullshit. I'm not asking for stupid
>> comments! I'm asking for respect for maintainers and other
>> programmers.
>
> +100
>
> The same goes for class comments too, duh.
>
> One problem is that it is hard to check the quality/meaning of the comment.
>
> "Comment later" would probably pass any check, as would "I am class XYZ".
>
> Also,
>
> name
>  "Returns the receiver's name"
>  ^ name
>
> Would also pass a simple test, while it is quite useless.
>
> I would say that any public, non-trivial methods need a comment.
>
> So human judgement will be needed.
>
> Sven

Reply | Threaded
Open this post in threaded view
|

Re: About method comments

Esteban A. Maringolo
In reply to this post by Sven Van Caekenberghe-2
2018-02-09 8:10 GMT-03:00 Sven Van Caekenberghe <[hidden email]>:
> name
>   "Returns the receiver's name"
>   ^ name
>
> Would also pass a simple test, while it is quite useless.
>
> I would say that any public, non-trivial methods need a comment.

Commenting an accesor is redundant, IMO.

And rename refactorings usually don't rename the comments (hopefully).

However I think that having a public guideline on how to comment
methods would be positive for the community (if these rules are
consensual).
After that some tools can use these guidelines to generate comments on
their own, or if you don't know how to comment, simply copy the
templates from the guide.

E.g. Private methods in Dolphin always start with "Private - ...", if
you remove the "private" category from the method (methods can belong
to multiple categories), then it removes the "Private - " prefix from
the comment as well.

Regards,

--
Esteban.

Reply | Threaded
Open this post in threaded view
|

Re: About method comments

Jan Vrany
Hi Esteban,

On Fri, 2018-02-09 at 15:17 -0300, Esteban A. Maringolo wrote:
>
> And rename refactorings usually don't rename the comments
> (hopefully).
>
Why hopefully? Java IDEs rename references to the method also
in comments, I found it very nice. Why it should not? I'm just curious.

Best, Jan

Reply | Threaded
Open this post in threaded view
|

Re: About method comments

Stephane Ducasse-3
You see I take some core classes and I read the code and I comment
when I understand what a method does.
And I do that 15 min from time to time. And just doing this will improve Pharo.
When I learn something I take 2 min to add a comment.

Stef


On Fri, Feb 9, 2018 at 9:13 PM, Jan Vrany <[hidden email]> wrote:

> Hi Esteban,
>
> On Fri, 2018-02-09 at 15:17 -0300, Esteban A. Maringolo wrote:
>>
>> And rename refactorings usually don't rename the comments
>> (hopefully).
>>
> Why hopefully? Java IDEs rename references to the method also
> in comments, I found it very nice. Why it should not? I'm just curious.
>
> Best, Jan
>

Reply | Threaded
Open this post in threaded view
|

Re: About method comments

Sean P. DeNigris
Administrator
In reply to this post by Esteban A. Maringolo
Esteban A. Maringolo wrote
> Commenting an accesor is redundant, IMO.

Typically, yes, and there are other examples.


Esteban A. Maringolo wrote
> I think that having a public guideline on how to comment
> methods would be positive for the community

Interesting idea. Any suggestions?



-----
Cheers,
Sean
--
Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html

Cheers,
Sean
Reply | Threaded
Open this post in threaded view
|

Re: About method comments

Stephane Ducasse-3
A method comment should tell
- what it is doing, what are the preconditions
- then some concerns about the implementation

You can give a try to document methods of fileSystem or SUnit as Katas.

Stef


On Sat, Feb 10, 2018 at 5:54 AM, Sean P. DeNigris <[hidden email]> wrote:

> Esteban A. Maringolo wrote
>> Commenting an accesor is redundant, IMO.
>
> Typically, yes, and there are other examples.
>
>
> Esteban A. Maringolo wrote
>> I think that having a public guideline on how to comment
>> methods would be positive for the community
>
> Interesting idea. Any suggestions?
>
>
>
> -----
> Cheers,
> Sean
> --
> Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html
>

Reply | Threaded
Open this post in threaded view
|

Re: About method comments

Bing Liang
In reply to this post by Stephane Ducasse-3
Hi, Stef
I have an idea for this problem,
1. method should have it's comment like class comment
2. method comment has two versions, one for developer another for reader
3. developder's comment will be saved in source or changes file
4. reader's comment will be saved in its own file
5. system browser can load  reader's comment of method when you want to read or write 

reader can write his comment using his native language, we can share all reader's comments on internet.

Best regards

Bing Liang