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
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 wrote:
> Esteban A.
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?
-
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
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,
2018-02-09 8:10 GMT-03:00 Sven Van Caekenberghe :
> 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
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 :
>
>
>
>> On 9 Feb 2018, at 12:04, Stephane Ducasse wrote:
>>
>> Hi guys
>>
>> From
> On 9 Feb 2018, at 12:04, Stephane Ducasse 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