[Pharo-users] On Class and Method comments

Jimmie Houchin jlhouchin at gmail.com
Tue May 17 14:06:32 EDT 2016


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 
> <mailto: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 <mailto: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 <mailto: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/dca6e47e/attachment.html>


More information about the Pharo-users mailing list