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.
On 9 Feb 2018, at 12:04, Stephane Ducasse <stepharo.self@gmail.com> 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
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 <sven@stfx.eu>:
On 9 Feb 2018, at 12:04, Stephane Ducasse <stepharo.self@gmail.com> 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
2018-02-09 8:10 GMT-03:00 Sven Van Caekenberghe <sven@stfx.eu>:
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.
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
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 <jan.vrany@fit.cvut.cz> 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
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
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 <sean@clipperadams.com> 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
Great Stef! Lorenzo -----Messaggio originale----- Da: Pharo-dev [mailto:pharo-dev-bounces@lists.pharo.org] 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.
participants (7)
-
Esteban A. Maringolo -
Jan Vrany -
Lorenzo Schiavina -
Norbert Hartl -
Sean P. DeNigris -
Stephane Ducasse -
Sven Van Caekenberghe