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.uh...@gmail.com
<mailto:i.uh...@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
<jlhouc...@gmail.com <mailto:jlhouc...@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.al...@gmail.com <mailto:kilon.al...@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 ?
