Interoperability TODOs
Jesse Jones
MarshalStringsInPInvokeDeclarationsRule.
Just in case you've forgotten, I also seem to still have quite a few
of Design TODOs queued up.
-- Jesse
Sebastien Pouliot
Please commit.
Sebastien
Sebastien Pouliot
Did I miss an email ? I don't see any answer (after mine) on my email
client, nor on the group email archive pertaining the Design namespace.
http://groups.google.com/group/gendarme/browse_thread/thread/b30042514f6b62d8?hl=en
Sebastien
Jesse Jones
I didn't check the above, but according to my email I sent it out on
July 10. But here it is again. It covers AvoidSmallNamespaceRule,
DeclareEventHandlersCorrectlyRule,
DontDeclareProtectedFieldsInSealedClassRule,
AttributeArgumentsShouldHaveAccessorsRule, and
AvoidMultidimensionalIndexerRule.
-- Jesse
Sebastien Pouliot
This look like the same patch. My reply is visible from the above url.
It also explains why configurable properties should be handled
differently (here and in the maintainability patch).
Sebastien
Jesse Jones
On Jul 26, 2009, at 5:34 PM, Sebastien Pouliot wrote:
>
> On Sun, 2009-07-26 at 17:16 -0700, Jesse Jones wrote:
>> On Jul 26, 2009, at 4:39 PM, Sebastien Pouliot wrote:
>>
>>>
>>> On Fri, 2009-07-24 at 18:30 -0700, Jesse Jones wrote:
>>>> Here's a patch for MarshalBooleansInPInvokeDeclarationsRule and
>>>> MarshalStringsInPInvokeDeclarationsRule.
>>>>
>>>> Just in case you've forgotten, I also seem to still have quite a
>>>> few
>>>> of Design TODOs queued up.
>>>
>>> Did I miss an email ? I don't see any answer (after mine) on my
>>> email
>>> client, nor on the group email archive pertaining the Design
>>> namespace.
>>>
>>> http://groups.google.com/group/gendarme/browse_thread/thread/b30042514f6b62d8?hl=en
>>
>> I didn't check the above, but according to my email I sent it out on
>> July 10. But here it is again. It covers AvoidSmallNamespaceRule,
>> DeclareEventHandlersCorrectlyRule,
>> DontDeclareProtectedFieldsInSealedClassRule,
>> AttributeArgumentsShouldHaveAccessorsRule, and
>> AvoidMultidimensionalIndexerRule.
>
> This look like the same patch.
It is.
> My reply is visible from the above url.
I don't think I got your reply: it's not in my inbox or trash.
>
> It also explains why configurable properties should be handled
> differently (here and in the maintainability patch).
1) If we're going to tell people that a setting is configurable then
we have to tell people how. The current situation where we tell people
that a property can be set but don't tell them how or even what the
property name is is terrible.
2) We should document the system as it exists today. When and if the
GUI runners are updated to support changing these properties we can
update the documentation then, but at least in the meantime some of
our users can change them.
Currently the text in question reads "The default can be changed using
the --config switch and the 'Minimum' property." I suppose there could
be some confusion about whether this is a gendarme or wizard switch so
perhaps we should change it to "the gendarme --config switch." But if
you don't like this I'd be in favor of removing all mention of user
configurable defaults.
-- Jesse
Sebastien Pouliot
well that's between Google and your ISP then (or in your spam ;-)
> >
> > It also explains why configurable properties should be handled
> > differently (here and in the maintainability patch).
>
> 1) If we're going to tell people that a setting is configurable then
> we have to tell people how. The current situation where we tell people
> that a property can be set but don't tell them how or even what the
> property name is is terrible.
Well terrible sounds just... terrible. I honestly believe that, in the
scale of the universe, we're a few millimeters above this. Anyway the
chosen adjective is less important than the solution :)
> 2) We should document the system as it exists today. When and if the
> GUI runners are updated to support changing these properties we can
> update the documentation then, but at least in the meantime some of
> our users can change them.
Now let's not move from something bad to something else 'bad' (even if
we gain a few more millimeters) because documenting the runner(s) inside
each/most rule(s) is definitively bad and will become a maintenance
nightmare.
At some point 'stable' rules needs to have 'stable' documentation, i.e.
that won't depend on runner changes. I'm hoping that with your recent
work and the (after 2.6) documentation of the properties that we will
reach this 'stable' documentation nirvana.
> Currently the text in question reads "The default can be changed using
> the --config switch and the 'Minimum' property." I suppose there could
> be some confusion about whether this is a gendarme or wizard switch so
> perhaps we should change it to "the gendarme --config switch."
I'm not sure adding this phrase will remove all, or any, confusion. Half
of our users are using the wizard, and many of the other half* (console)
have never used/heard-of the --config switch.
* I'm pretty curious how that percentage will evolve and how the
NAnt/CC.NET tasks will influence this.
What's really needed (let's say for 2.6) is adding an HOWTO (and a link
in the FAQ**) to the wiki that describe how to use this feature. So
anyone reading about "default values" or "configurable properties" will,
if interested, find the feature (and how to use it) using the FAQ.
** like discussed on IRC the man page should have some
information too
> But if
> you don't like this I'd be in favor of removing all mention of user
> configurable defaults.
This will makes it harder to move forward and document them properly in
the future. However you're welcome to remove them as long as they are
documented (well listed) in the group 'rules' document.
Sebastien
Cedric Vivier
because documenting the runner(s) inside
each/most rule(s) is definitively bad and will become a maintenance
nightmare.
If I did not miss something above is the only real problem about documenting _rule's_ configurable properties right?
Configurable properties (and their defaults/possible values) stay the same whatever the runner is afaik, we could remove the "--config switch" sentence and just document the properties ?
E.g:
""
<list>
<listheader>
<term>Optional configurable properties</term>
<description>To modify a property on your runner refer to its documentation (or read http://wiki/gendarme/configurable-properties)</description>
</listheader>
<item>
<term>SuccessLowerLimit</term>
<description>A float number representing the LoC value under which rule will succeed (default: 0.5).</description>
</item> ...
</list>
"""
Cheers,
Jesse Jones
On Jul 27, 2009, at 8:17 PM, Cedric Vivier wrote:
> Hey,
>
> On Tue, Jul 28, 2009 at 5:38 AM, Sebastien Pouliot <sebastie...@gmail.com
> > wrote:
> because documenting the runner(s) inside
> each/most rule(s) is definitively bad and will become a maintenance
> nightmare.
>
> If I did not miss something above is the only real problem about
> documenting _rule's_ configurable properties right?
Yes.
>
>
> Configurable properties (and their defaults/possible values) stay
> the same whatever the runner is afaik, we could remove the "--config
> switch" sentence and just document the properties ?
I think you're right: if we make it clear that these are
config(urable) properties then console users will have a decent idea
of what to try and gendarme-wizard/MD addin users should be able to
fairly easily figure it out as well when and if they support
configuring properties.
-- Jesse
Jesse Jones
On Jul 27, 2009, at 2:38 PM, Sebastien Pouliot wrote:
>
> Hello Jesse,
>
> On Sun, 2009-07-26 at 23:38 -0700, Jesse Jones wrote:
>>
>> 1) If we're going to tell people that a setting is configurable then
>> we have to tell people how. The current situation where we tell
>> people
>> that a property can be set but don't tell them how or even what the
>> property name is is terrible.
>
> Well terrible sounds just... terrible. I honestly believe that, in the
> scale of the universe, we're a few millimeters above this. Anyway the
> chosen adjective is less important than the solution :)
Well, we are 1) telling people they can do something nifty 2) not
documenting the mechanism (custom config files) or the property names.
This is terrible. About the only thing I can think of that would be
worse in documentation is if is flat-out wrong.
>
>
>> 2) We should document the system as it exists today. When and if the
>> GUI runners are updated to support changing these properties we can
>> update the documentation then, but at least in the meantime some of
>> our users can change them.
>
> Now let's not move from something bad to something else 'bad' (even if
> we gain a few more millimeters) because documenting the runner(s)
> inside
> each/most rule(s) is definitively bad and will become a maintenance
> nightmare.
I prefer to think of it as moving from bad to less bad. My goal is
simply to improve the documentation: not make it perfect today and
certainly not to make it perfect for whatever the future may bring.
-- Jesse
Sebastien Pouliot
On Tue, 2009-07-28 at 11:17 +0800, Cedric Vivier wrote:
> Hey,
>
> On Tue, Jul 28, 2009 at 5:38 AM, Sebastien Pouliot
> <sebastie...@gmail.com> wrote:
> because documenting the runner(s) inside
> each/most rule(s) is definitively bad and will become a
> maintenance
> nightmare.
>
> If I did not miss something above is the only real problem about
> documenting _rule's_ configurable properties right?
yes
> Configurable properties (and their defaults/possible values) stay the
> same whatever the runner is afaik, we could remove the "--config
> switch" sentence and just document the properties ?
but it's not about documenting them (or not) but how to document them so
it can be both useful and maintainable.
> E.g:
> ""
> <list>
> <listheader>
> <term>Optional configurable properties</term>
> <description>To modify a property on your runner refer to its
> documentation (or read
> http://wiki/gendarme/configurable-properties)</description>
> </listheader>
^ that's the kind of duplication that will make this harder (than it
needs to be) to maintain (e.g. link change).
> <item>
> <term>SuccessLowerLimit</term>
> <description>A float number representing the LoC value under
> which rule will succeed (default: 0.5).</description>
> </item> ...
> </list>
> """
Using <list> would work today but it has drawbacks, some that already
exists today (a, b), some that will limit us in the future (c, d).
Now using xml documentation on the (selected/supported) properties will:
a) avoid potential typos (e.g. SuccessLowerLimit
versus SuccessLowerLimits) which would be hard to find by end users
without checking the source code. Using xmldoc will ensure the
properties are valid (well identical to what is required ;-)
b) track what is (and what needs) to the documented. If we can't list
what's documented versus what exists then there will be holes in the
documentation. We still need a tool (to ensure this) but it would be a
(much) simpler one;
c) allow the xmldoc->wiki tool to treat them specially (e.g. adding a
link to configuration documentation without having this link embedded
into each rule) and uniformly [1]
d) allow a runner to build an intelligent UI above the rules and extract
the right documentation for each configurable option [1] (e.g. a
property grid-like UI to set options). That's not some far-fetched
futuristic idea, the wizard is waiting for this to get configurable
properties.
[1] Using <list>, non-exclusively (i.e. it's being used for
other things too), inside the type <summary> would not make
these impossible but much harder to parse correctly (even if
complete and without typos) than documenting the properties
themselves;
The downside is that the xmldoc2wiki tool does not yet support this. I
have a long list of things I need (or like) to do before we branch 2.6
and I was not planning on updating it to support properties.
But as soon as 2.6 is branched everyone is welcome to document the
configurable properties* (and doing so will push me to update
xmldoc2wiki before 2.8 ;-).
* in fact this should be done in concert with adding the
System.Component attributes on them - clearly splitting what is
user-configurable and what's the rule internal state.
Sebastien
Sebastien Pouliot
On Tue, 2009-07-28 at 08:10 -0700, Jesse Jones wrote:
>
> On Jul 27, 2009, at 2:38 PM, Sebastien Pouliot wrote:
>
> >
> > Hello Jesse,
> >
> > On Sun, 2009-07-26 at 23:38 -0700, Jesse Jones wrote:
> >>
> >> 1) If we're going to tell people that a setting is configurable then
> >> we have to tell people how. The current situation where we tell
> >> people
> >> that a property can be set but don't tell them how or even what the
> >> property name is is terrible.
> >
> > Well terrible sounds just... terrible. I honestly believe that, in the
> > scale of the universe, we're a few millimeters above this. Anyway the
> > chosen adjective is less important than the solution :)
>
> Well, we are 1) telling people they can do something nifty 2) not
> documenting the mechanism (custom config files) or the property names.
Good point about the mechanism itself.
> This is terrible. About the only thing I can think of that would be
> worse in documentation is if is flat-out wrong.
Maybe I must have seen too many terrible things that it affected my
definition of term ;-) but, whatever the name, I agree that it could be
better.
> >> 2) We should document the system as it exists today. When and if the
> >> GUI runners are updated to support changing these properties we can
> >> update the documentation then, but at least in the meantime some of
> >> our users can change them.
> >
> > Now let's not move from something bad to something else 'bad' (even if
> > we gain a few more millimeters) because documenting the runner(s)
> > inside
> > each/most rule(s) is definitively bad and will become a maintenance
> > nightmare.
>
> I prefer to think of it as moving from bad to less bad. My goal is
> simply to improve the documentation: not make it perfect today and
> certainly not to make it perfect for whatever the future may bring.
and my goal is to (try to) get the most of any efforts wrt our roadmap.
Now I won't refuse better documentation (nor anything else that is
maintainable ;-) but I don't believe such changes will live very long -
reducing your time worth, which is something that pains me.
What about this?
* you start with documenting the mechanism itself. Anyway documenting
the rules without the mechanism won't help end-users a bit. OTOH even if
the properties are not totally documented, having the mechanism
documented makes them (the one documented) useful.
* I'll have a look, asap (like the next two nights), at xmldoc2wiki to
see if I can hack properties support into it. At a minimum so it does
not "break" generating rules documentation for 2.6 (with more work
later) so we don't get caught at branch time.
* Once xmldoc2wiki is ready[1] (i.e. it can output the extra content in
some form) or, worse case, "aware" (it can ignore them for 2.6
docs) then we (as in everyone) start documenting the properties and
adding the S.ComponentModel attributes [2].
Sebastien
[1] in the mean time, if any, I'd really like an HOWTO about your latest
rule since otherwise, I fear, it will be overlooked in 2.6.
[2]
http://www.mono-project.com/Gendarme.Roadmap#Gendarme_2.8.2B_.28in_planning.29
Sebastien Pouliot
ok, I got it almost ready last night. I just need to tweak how it looks
on the wiki (i.e. the parsing is ok).
> * Once xmldoc2wiki is ready[1] (i.e. it can output the extra content in
> some form) or, worse case, "aware" (it can ignore them for 2.6
> docs) then we (as in everyone) start documenting the properties and
> adding the S.ComponentModel attributes [2].
I'll email an example of the above (attributes) in a new thread.
Jesse Jones
r139187
-- Jesse
Jesse Jones
On Jul 29, 2009, at 2:58 PM, Sebastien Pouliot wrote:
>
>> * you start with documenting the mechanism itself. Anyway documenting
>> the rules without the mechanism won't help end-users a bit. OTOH
>> even if
>> the properties are not totally documented, having the mechanism
>> documented makes them (the one documented) useful.
I'll see if I can add a section to the man page on the config file,
but I'd prefer to do this after finishing up the rules.
-- Jesse
Sebastien Pouliot
That's ok - it's still better than the current situation ;-)
Thanks,
Sebastien
Jesse Jones
of documenting configurable properties and some of the TODOs I added
have been moved to
<http://groups.google.com/group/gendarme/web/rules-todo-comments-enhancements?hl=en
>.
-- Jesse
Sebastien Pouliot
Please commit.
Thanks
Sebastien
Jesse Jones
r139718
-- Jesse