[Pharo-users] On Class and Method comments

Jimmie Houchin jlhouchin at gmail.com
Tue May 17 11:32:38 EDT 2016

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.

Right now I am working on parsing a bunch of xml files. Third party data 
sources. 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.

> 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.


> 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/eb9f2840/attachment.html>

More information about the Pharo-users mailing list