|
|
One of the things mentioned at PharoDays, which actually could have been a boring talk but in fact caught my attention due to being well researched and presented - was the question of commenting in Pharo (thanks presenters).
However, the question of class comments and how many classes actually follow the suggested template was an interesting point. Having earlier heard feenk talk about making documentation fun and usable, it struck me that the current template and even basic tooling are a million miles from this - and in fact run the risk of promoting redundancy and drudgery…. Sharp claims, but hey we keep striving for better in Pharo.
I like the CRC parallel, but I think its the “public api” and even the "internal representation" bits that annoy me. Surely the public api is what our categories are for? So repeating that is bad (just indicating the category that is the api would be better - and potentially inlining it automatically in the comment would be more useful - this does raise the problem that methods can only be in 1 category, and maybe this is what this template is trying to cover up? Equally, the internal representation should not just be to describe instance variables (we could just give them better names, and possibly double up on the class builder idea where adding a variable could also let you explain right there what its for) but more about the bigger picture - why a dictionary ivar vs a collection.
If its a while before we get to full GT, can’t we tart up the class comment pane and make it a bit more interactive (like a form) and able to inline docs (or show generated info) so its not retyped?
I’m sure there are some simple tricks we could do to improve the situation immensely to address the premise of the talk?
Tim
|
Locked
