We are cleaning spec and the fact that method selectors are used everywhere in pragmas as meta description makes the navigation terrible. I'm removing them to be able to understand who is really calling the methods. So there is probably a lesson there. Stef
Could you provide a sample, so this anti-pattern is more clear. cheers -ben On Fri, Feb 27, 2015 at 12:08 AM, stepharo <stepharo@free.fr> wrote:
We are cleaning spec and the fact that method selectors are used everywhere in pragmas as meta description makes the navigation terrible. I'm removing them to be able to understand who is really calling the methods. So there is probably a lesson there.
Stef
On 26 Feb 2015, at 5:12 , Ben Coman <btc@openInWorld.com> wrote:
Could you provide a sample, so this anti-pattern is more clear. cheers -ben
acceptBlock: aBlockWithOneArgument <api: #block getter: #acceptBlock registration: #whenAcceptBlockChanged:> "Set the block to perform when the text is accepted. The block must have one argument, which will be the accepted text. The block can return false if the candidate text is to be rejected" Senders of acceptBlock / whenAcceptBlockChanged now includes acceptBlock: I guess the pragma is used to autogenerate documentation in sync with the source, but then it's a bit strange that the description is in a comment rather than the pragma itself. Haven't seen a setter/getter pair that deviates from the standard yet, but one must exist for there to be a keyword reserved for it in the pragma... right? Cheers, Henry
I think that fundamentally you should not use pragmas for documentation. I guess that people use it to be able to provide minimal structure for their documentation. A better solution would be to have a simple convention for this kind of structure that is easy to parse, e.g using newlines to separate the âkeywordsâ and their âvaluesâ and just have a comment. For example: Now: <api: #block getter: #acceptBlock registration: #whenAcceptBlockChanged:> Comment convention: â api: #block getter: #acceptBlock registration: #whenAcceptBlockChanged: " Easy to parse, and easy to write conversion logic for batch transformation of these comments.
On Feb 26, 2015, at 13:12, Ben Coman <btc@openInWorld.com> wrote:
Could you provide a sample, so this anti-pattern is more clear. cheers -ben
On Fri, Feb 27, 2015 at 12:08 AM, stepharo <stepharo@free.fr <mailto:stepharo@free.fr>> wrote: We are cleaning spec and the fact that method selectors are used everywhere in pragmas as meta description makes the navigation terrible. I'm removing them to be able to understand who is really calling the methods. So there is probably a lesson there.
Stef
---> Save our in-boxes! http://emailcharter.org <--- Johan Fabry - http://pleiad.cl/~jfabry PLEIAD lab - Computer Science Department (DCC) - University of Chile
On Fri, Feb 27, 2015 at 12:53 AM, Johan Fabry <jfabry@dcc.uchile.cl> wrote:
I think that fundamentally you should not use pragmas for documentation. I guess that people use it to be able to provide minimal structure for their documentation. A better solution would be to have a simple convention for this kind of structure that is easy to parse, e.g using newlines to separate the âkeywordsâ and their âvaluesâ and just have a comment. For example:
Now: <api: #block getter: #acceptBlock registration: #whenAcceptBlockChanged:>
Comment convention: â api: #block getter: #acceptBlock registration: #whenAcceptBlockChanged: "
Easy to parse, and easy to write conversion logic for batch transformation of these comments.
And MOST importantly, easy to identify that it doesn't affect program execution! cheers -ben
On Feb 26, 2015, at 13:12, Ben Coman <btc@openInWorld.com> wrote:
Could you provide a sample, so this anti-pattern is more clear. cheers -ben
On Fri, Feb 27, 2015 at 12:08 AM, stepharo <stepharo@free.fr> wrote:
We are cleaning spec and the fact that method selectors are used everywhere in pragmas as meta description makes the navigation terrible. I'm removing them to be able to understand who is really calling the methods. So there is probably a lesson there.
Stef
participants (4)
-
Ben Coman -
Henrik Johansen -
Johan Fabry -
stepharo