[Pharo-users] On Class and Method comments

Dimitris Chloupis kilon.alios at gmail.com
Tue May 17 15:14:19 EDT 2016


The problem I have with braking methods to much smaller ones is that it
makes browsing code far more tedious. I think the 10 lines limit is fine
but once you get 5 lines it becomes unnecessarily modular. I think like all
things comments and braking methods should be exercised with some critical
thinking.

I also dont see the big deal of commenting your classes and at least a few
key methods. In any case, complaining leads nowhere, my question was merely
to help out with the comments.

If you ask me and you have not , pharo would be cool to have a modular
system where someone can hide and unhide comments or have summary comments
and detailed comments , so that we integrate documentation inside the
image. Maybe one day I will be able to tackle this as well.

On Tue, May 17, 2016 at 9:07 PM Jimmie Houchin <jlhouchin at gmail.com> wrote:

> You are absolutely right. Many without comments. Some of which may not
> need comments as they are self revealing in what and why. But many which do
> need some good comments.
>
> As I read Peter's email. What he was saying is that my intent or why can
> be placed in the method comment when broken into smaller methods. Instead
> of it being inline in a larger method. Sometimes that is true.
>
> What I am encountering sometimes at the moment in parsing the XML is ugly
> XML source. I have methods with way too many ifTrue: [] ifFalse: [ ifTrue:
> [] ifFalse: []] ... nested conditionals. Sometimes this is not easy to
> break up into smaller methods. All of the state is in the nested
> conditionals.
>
> In this situation it is occurring as I parse the 16MB XML file and
> encounter situations in the source. The debugger pops up. I have to deal
> with whatever. Sometimes this needs some inline comments. Sometimes after I
> have the code working. I may or may not be able to reasonably refactor into
> something nicer and cleaner. Sometimes it is more important to move on to
> other more pressing issues.
>
> Sometimes I think this why we have uncommented or poorly commented code in
> the image. It is working. I need to move on. Really we want some of the big
> movers to have this liberty. And allow some of us to follow behind, learn
> and comment.
>
> Thank you for this effort to help improve our home (image). :)
> I need to find time and learn to contribute also.
>
>
> Jimmie
>
>
>
> On 05/17/2016 11:59 AM, Dimitris Chloupis wrote:
>
> ok guys then it seems all is as expected
>
> I am a fan of inline comments when needed, I am with full agreement with
> Jimmie here , braking methods to smaller methods cannot reveal intend, an
> inline comment can but thats not big deal i can put everything on the start
> so everyone is happy
>
> The problem here is that there many classes with no comments and methods
> that inline comments is the least of my worries.
>
> On Tue, May 17, 2016 at 7:20 PM Peter Uhnák <i.uhnak at gmail.com> wrote:
>
>>
>> Now, I only know that comments in block closures are placed behind the
>>> block code.
>>> Do you know more examplmes where the formatter still misplaces the
>>> comment.
>>
>>
>> Maybe just comments now? I've added a formatting configuration that
>> preserved vertical white space (and I believe also comment position,
>> because I used to write inline comments), but I think it was lost during
>> migration to BlueInk. But I'll have a look.
>>
>>
>> On Tue, May 17, 2016 at 5:32 PM, Jimmie Houchin <jlhouchin at gmail.com>
>> wrote:
>>
>>> On 05/17/2016 01:40 AM, Peter Uhnák wrote:
>>>
>>> As a note, maybe try to avoid inline comments unless formatter is fixed,
>>> because autoformatting _will_ misplace them. (Not to mention that imho
>>> inline comments in Smalltalk are a result of a bad design… if you need an
>>> inline comment, maybe turn that into actual code).
>>>
>>>
>>> I disagree with the comment about inline comments being bad design. At
>>> least as a broadly applied as the above was.
>>>
>>> Comments often say "Why" we did something. Code says "How" or "What" we
>>> are doing. I have encountered many times where if I did not have a comment
>>> for the "Why". Then at a later date when I don't remember the "Why". I
>>> encounter code that looks strange and I am tempted to refactor and
>>> consequently would introduce bugs.
>>>
>>
>> This doesn't necessarily dispute my point. If you need to have inline
>> comments then you are most likely doing in the method more then you should,
>> otherwise you can just put the intent in the method comment.
>> Of course in real world we have looooong methods in both ancient and
>> (unfortunately) new systems, and adding a comment is better then nothing.
>> Assuming of course, that the comment is correct… because a wrong or
>> misleading comment can do more harm than good… that's why I _personally_
>> (thus the imho in the original note) prefer code over comments. Because
>> code is what actually happens.
>>
>> And finally I rarely (unless the method is a real mess) have problem
>> understanding a single method (I can poke it, look at tests, go through the
>> code, ...). What I usually lack is high-level overview that would tell me
>> how the system overall works. That you cannot read from method (or class)
>> comments.
>>
>>
>>
>>> Right now I am working on parsing a bunch of xml files. Third party data
>>> sources.
>>>
>>
>> Is it XML or XMI? Couple of weeks back a wrote a simple utility
>> for Synectique to help with analyzing and processing XMI files. Maybe it
>> could help you a bit https://github.com/peteruhnak/xmi-analyzer ?
>>
>>
>>> There is ugliness in the world. I have to clean the ugliness in order to
>>> be able to parse the files. There is no option if I want to do this. I have
>>> no control over the sources. I am not interested in engaging outside
>>> bureaucratic policies and people in order to change their procedures and
>>> policies so that I can have better sources. How often would I be willing to
>>> fight this losing battle.
>>>
>>> The only solution is to do ugly things, for good reasons and comment
>>> them well. So that I know not just what I did, but why.
>>>
>>> I also believe there is some conflicting policy in the code critic or
>>> whatever is telling me my method is too long.
>>>
>>> I have frequently written methods that had a few temp vars with nice
>>> informative names. and the method is involved enough to use these vars
>>> multiple times. I get this nice information informing me my method is long.
>>> Or in Pharo4 going yellow and then red. :)
>>>
>>> However many times if I made these vars short, like x, y, z. Then the
>>> method is a perfectly fine length. Ugh. I am then being punished for length
>>> of names. I have seen this a lot.
>>>
>>
>> Well Code Critic doesn't force you to do all these things. But every time
>> you transgress the rule you should consider whether it's worth it. (And
>> maybe even auto-ignore the rule.)
>>
>>
>>> In any case, there are no guidelines afaik… otherwise we would have
>>> comments everywhere already. :)
>>>
>>>
>>> Not necessarily. People are busy. Sometimes getting working code out is
>>> more important than commenting it well.
>>>
>>> For example. And I am not saying this is true. It is simply and example.
>>> While pressure is mounting to release Pharo 5. The few over worked people
>>> involved in that final process. Finishing up the final things, might be
>>> pragmatic and let working code go without comments. Or in some similar
>>> situation by a code contributor.
>>>
>>> Then their are people like myself and Dimitris who might not feel
>>> confident in submitting comments for some of these areas without
>>> appropriate guidelines. We want to improve the situation not make bad
>>> examples of what not to do. :)
>>>
>>> Just some of my opinions.
>>>
>>
>>
>> And finally there is never one rule that would fit all, and any guideline
>> or whatever will find an edge case. But Pharo is moving fast… so I don't
>> see why you wouldn't feel confident about commenting. The worst case
>> scenario is that something breaks and we have a chance to learn something
>> from the mistake.
>>
>> Peter
>>
>>
>>>
>>>
>>> Jimmie
>>>
>>>
>>> Perhaps one thing regarding class comments: There was a push to use
>>> PIllar there if you need formatting, but I am not sure what is the current
>>> status of that.
>>>
>>> Peter
>>>
>>> On Tue, May 17, 2016 at 12:04 AM, Dimitris Chloupis <
>>> kilon.alios at gmail.com> wrote:
>>>
>>>> I really like to start writing some class and method comments to make
>>>> Pharo image more beginner friendly. Are there any guidelines when and how
>>>> to comment classes and methods ? What about inline comments ?
>>>>
>>>
>>>
>>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/attachments/20160517/6628a8e2/attachment.html>


More information about the Pharo-users mailing list