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 <jlhouc...@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.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> >> 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> 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 ? >>>> >>> >>> >>> >
