26 Jul
2013
26 Jul
'13
10:47 p.m.
Hi,
To promote contribution and encourage code brevity, I would like to remove
the rule that we fail the build over a missing javadoc on a non-public
field.
It's important to understand, this is *not* about encouraging developers
to skimp on documentation!
There are obvious cases such as 'logger' where the role of the field is
blatantly clear and forced documentation is at best useless and at worst
counterproductive because it creates an information overload for the code
reader and hides the comments which the author really wanted to be seen.
+1 for dropping this rule
Thanks,
Caleb
27 Jul
27 Jul
10:45 a.m.
New subject: [xwiki-devs] [VOTE] Relax checkstyle rule about javadoc on non-public class members.
+1
Thanks
On Fri, Jul 26, 2013 at 10:47 PM, Caleb James DeLisle <
calebdelisle(a)lavabit.com> wrote:
Hi,
To promote contribution and encourage code brevity, I would like to remove
the rule that we fail the build over a missing javadoc on a non-public
field.
It's important to understand, this is *not* about encouraging developers
to skimp on documentation!
There are obvious cases such as 'logger' where the role of the field is
blatantly clear and forced documentation is at best useless and at worst
counterproductive because it creates an information overload for the code
reader and hides the comments which the author really wanted to be seen.
+1 for dropping this rule
Thanks,
Caleb
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
--
Denis Gervalle
SOFTEC sa - CEO
eGuilde sarl - CTO
2:19 p.m.
New subject: [xwiki-devs] [VOTE] Relax checkstyle rule about javadoc on non-public class members.
+1
On Fri, Jul 26, 2013 at 10:47 PM, Caleb James DeLisle
<calebdelisle(a)lavabit.com> wrote:
Hi,
To promote contribution and encourage code brevity, I would like to remove
the rule that we fail the build over a missing javadoc on a non-public
field.
It's important to understand, this is *not* about encouraging developers
to skimp on documentation!
There are obvious cases such as 'logger' where the role of the field is
blatantly clear and forced documentation is at best useless and at worst
counterproductive because it creates an information overload for the code
reader and hides the comments which the author really wanted to be seen.
+1 for dropping this rule
Thanks,
Caleb
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
--
Thomas Mortagne
3:48 p.m.
New subject: [xwiki-devs] [VOTE] Relax checkstyle rule about javadoc on non-public class members.
On 07/26/2013 04:47 PM, Caleb James DeLisle wrote:
Hi,
To promote contribution and encourage code brevity, I would like to remove
the rule that we fail the build over a missing javadoc on a non-public
field.
It's important to understand, this is *not* about encouraging developers
to skimp on documentation!
There are obvious cases such as 'logger' where the role of the field is
blatantly clear and forced documentation is at best useless and at worst
counterproductive because it creates an information overload for the code
reader and hides the comments which the author really wanted to be seen.
+1 for dropping this rule
+1. The best rule about commenting code is that comments should only say
what the code can't. Sometimes it's hard to come up with a good
non-repetitive comment like:
/** The author of the document. */
private DocumentReference author;
/**
* Get the author of the document.
* @return the author of the document
*/
public DocumentReference getAuthor(){...}
/**
* Set the author of the document.
* @param author the new author of the document to set
*/
public void setAuthor(DocumentReference author){...}
Since most of our code is now components, we must continue to thoroughly
document all our APIs (roles), but internal implementation details are
better documented by inline comments that actually explain tricky points
in the code, instead of reexplaining parameter names that should already
have Understandable Names.
--
Sergiu Dumitriu
http://purl.org/net/sergiu
4:19 p.m.
Hi,
On Jul 27, 2013, at 3:48 PM, Sergiu Dumitriu <sergiu(a)xwiki.com> wrote:
Yes, for the repetitiveness, I've been using @see elements in all my code so that only
the getter is documented.
These are bad comments obviously… FTR I had put a small javadoc guide with some example
at:
http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HJavadocBestPra…
A good comment IMO is one that doesn't only explain what it represents but why
it's there and that shows an example when the data is untyped. For example:
/**
* The last person who made a modification to any part of this document (content,
objects, etc). Note that this is different from the creator who is the person who first
created the document. Example of author: "XWiki.Admin".
*/
private String author;
Suddenly it becomes interesting:
- we know it's about the last person who made a modification to any part of the
document which was not clear from the field (and it'll explain the difference with
contentAuthor too).
- we have an example showing what an author string looks like (of course using a
DocumentReference is even better since it's typed and clearly represents what is an
author)
With DocumentReference:
/**
* The last person who made a modification to any part of this document (content,
objects, etc). Note that it points to a reference to that author's document
representing it since we currently don't have a User object to represent a User.
*/
private DocumentReference author;
Future:
/**
* The last person who made a modification to any part of this document (content,
objects, etc).
*/
private User lastAuthor;
For this last example the comment becomes slightly less useful than in the previous
examples but it's still useful IMO.
On 07/26/2013 04:47 PM, Caleb James DeLisle wrote:
> Hi,
> To promote contribution and encourage code brevity, I would like to remove
> the rule that we fail the build over a missing javadoc on a non-public
> field.
>
> It's important to understand, this is *not* about encouraging developers
> to skimp on documentation!
In practice it is (as can be demonstrated by the state of the oldcore when we started
working on it back in 2005) :)
> There are obvious cases such as 'logger'
where the role of the field is
> blatantly clear and forced documentation is at best useless and at worst
> counterproductive because it creates an information overload for the code
> reader and hides the comments which the author really wanted to be seen.
Yes logger is a good example of a field for which it's hard to write an intelligent
comment ;)
+1 for
dropping this rule
+1. The best rule about commenting code is that comments should only say
what the code can't. Sometimes it's hard to come up with a good
non-repetitive comment like:
/** The author of the document. */
private DocumentReference author;
/**
* Get the author of the document.
* @return the author of the document
*/
public DocumentReference getAuthor(){...}
/**
* Set the author of the document.
* @param author the new author of the document to set
*/
public void setAuthor(DocumentReference author){…} Since most of our code is now components, we must
continue to thoroughly
document all our APIs (roles), but internal implementation details are
better documented by inline comments that actually explain tricky points
in the code, instead of reexplaining parameter names that should already
have Understandable Names.
I'm -0 but I'll follow the majority. It's not because it's hard to write
good comments that we shouldn't do it… Obviously there are cases when it's really
hard to find a good comment (like the logger for example) but you can be sure that not
mandating comments will not make them automagically appear even for harder to understand
cases. We can only hope that all the xwiki devs have by now been trained enough to write
javadoc comments with our past strategy that they'll continue to write them wherever
needed but even that will decay over time...
We'll see what happens :)
Thanks
-Vincent
4:29 p.m.
On Jul 27, 2013, at 4:19 PM, Vincent Massol <vincent(a)massol.net> wrote:
Hi,
On Jul 27, 2013, at 3:48 PM, Sergiu Dumitriu <sergiu(a)xwiki.com> wrote:
Yes, for the repetitiveness, I've been using @see elements in all my code so that
only the getter is documented.
These are bad comments obviously… FTR I had put a small javadoc guide with some example
at:
http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HJavadocBestPra…
A good comment IMO is one that doesn't only explain what it represents but why
it's there and that shows an example when the data is untyped. For example:
/**
* The last person who made a modification to any part of this document (content,
objects, etc). Note that this is different from the creator who is the person who first
created the document. Example of author: "XWiki.Admin".
A better note would be:
"Note that this is different from the content author who is the last person who made
modifications to only the content of the document (changes to the document's objects
or class doesn't change it)."
Thanks
-Vincent
On 07/26/2013 04:47 PM, Caleb James DeLisle
wrote:
> Hi,
> To promote contribution and encourage code brevity, I would like to remove
> the rule that we fail the build over a missing javadoc on a non-public
> field.
>
> It's important to understand, this is *not* about encouraging developers
> to skimp on documentation!
In practice it is (as can be demonstrated by the state of the oldcore when we started
working on it back in 2005) :)
> There are obvious cases such as
'logger' where the role of the field is
> blatantly clear and forced documentation is at best useless and at worst
> counterproductive because it creates an information overload for the code
> reader and hides the comments which the author really wanted to be seen.
Yes logger is a good example of a field for which it's hard to write an intelligent
comment ;)
+1 for
dropping this rule
+1. The best rule about commenting code is that comments should only say
what the code can't. Sometimes it's hard to come up with a good
non-repetitive comment like:
/** The author of the document. */
private DocumentReference author;
/**
* Get the author of the document.
* @return the author of the document
*/
public DocumentReference getAuthor(){...}
/**
* Set the author of the document.
* @param author the new author of the document to set
*/
public void setAuthor(DocumentReference author){…} */
private String author;
Suddenly it becomes interesting:
- we know it's about the last person who made a modification to any part of the
document which was not clear from the field (and it'll explain the difference with
contentAuthor too).
- we have an example showing what an author string looks like (of course using a
DocumentReference is even better since it's typed and clearly represents what is an
author)
With DocumentReference:
/**
* The last person who made a modification to any part of this document (content,
objects, etc). Note that it points to a reference to that author's document
representing it since we currently don't have a User object to represent a User.
*/
private DocumentReference author;
Future:
/**
* The last person who made a modification to any part of this document (content,
objects, etc).
*/
private User lastAuthor;
For this last example the comment becomes slightly less useful than in the previous
examples but it's still useful IMO.
Since most of our code is now components, we must
continue to thoroughly
document all our APIs (roles), but internal implementation details are
better documented by inline comments that actually explain tricky points
in the code, instead of reexplaining parameter names that should already
have Understandable Names.
I'm -0 but I'll follow the majority. It's not because it's hard to write
good comments that we shouldn't do it… Obviously there are cases when it's really
hard to find a good comment (like the logger for example) but you can be sure that not
mandating comments will not make them automagically appear even for harder to understand
cases. We can only hope that all the xwiki devs have by now been trained enough to write
javadoc comments with our past strategy that they'll continue to write them wherever
needed but even that will decay over time...
We'll see what happens :)
Thanks
-Vincent
29 Jul
29 Jul
10:11 a.m.
New subject: [xwiki-devs] [VOTE] Relax checkstyle rule about javadoc on non-public class members.
On Sat, Jul 27, 2013 at 5:19 PM, Vincent Massol <vincent(a)massol.net> wrote:
Hi,
On Jul 27, 2013, at 3:48 PM, Sergiu Dumitriu <sergiu(a)xwiki.com> wrote:
Yes, for the repetitiveness, I've been using @see elements in all my code so that
only the getter is documented.
These are bad comments obviously… FTR I had put a small javadoc guide with some example
at:
http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HJavadocBestPra…
A good comment IMO is one that doesn't only explain what it represents but why
it's there and that shows an example when the data is untyped. For example:
/**
* The last person who made a modification to any part of this document (content,
objects, etc). Note that this is different from the creator who is the person who first
created the document. Example of author: "XWiki.Admin".
*/
private String author;
Suddenly it becomes interesting:
- we know it's about the last person who made a modification to any part of the
document which was not clear from the field (and it'll explain the difference with
contentAuthor too).
- we have an example showing what an author string looks like (of course using a
DocumentReference is even better since it's typed and clearly represents what is an
author)
With DocumentReference:
/**
* The last person who made a modification to any part of this document (content,
objects, etc). Note that it points to a reference to that author's document
representing it since we currently don't have a User object to represent a User.
*/
private DocumentReference author;
Future:
/**
* The last person who made a modification to any part of this document (content,
objects, etc).
*/
private User lastAuthor;
For this last example the comment becomes slightly less useful than in the previous
examples but it's still useful IMO.
On 07/26/2013 04:47 PM, Caleb James DeLisle
wrote:
> Hi,
> To promote contribution and encourage code brevity, I would like to remove
> the rule that we fail the build over a missing javadoc on a non-public
> field.
>
> It's important to understand, this is *not* about encouraging developers
> to skimp on documentation!
In practice it is (as can be demonstrated by the state of the oldcore when we started
working on it back in 2005) :)
> There are obvious cases such as
'logger' where the role of the field is
> blatantly clear and forced documentation is at best useless and at worst
> counterproductive because it creates an information overload for the code
> reader and hides the comments which the author really wanted to be seen.
Yes logger is a good example of a field for which it's hard to write an intelligent
comment ;)
+1 for
dropping this rule
+1. The best rule about commenting code is that comments should only say
what the code can't. Sometimes it's hard to come up with a good
non-repetitive comment like:
/** The author of the document. */
private DocumentReference author;
/**
* Get the author of the document.
* @return the author of the document
*/
public DocumentReference getAuthor(){...}
/**
* Set the author of the document.
* @param author the new author of the document to set
*/
public void setAuthor(DocumentReference author){…} Since most of our code is now components, we must
continue to thoroughly
document all our APIs (roles), but internal implementation details are
better documented by inline comments that actually explain tricky points
in the code, instead of reexplaining parameter names that should already
have Understandable Names.
I'm -0 but I'll follow the majority. It's
not because it's hard to write good comments that we shouldn't do it… Obviously
there are cases when it's really hard to find a good comment (like the logger for
example) but you can be sure that not mandating comments will not make them automagically
appear even for harder to understand cases.
Sure, but at the same time mandating comments on private fields
doesn't imply we are all going to write useful comments. So I'm +1.
Thanks,
Marius
We can only hope that all the xwiki devs have by now
been trained enough to write javadoc comments with our past strategy that they'll
continue to write them wherever needed but even that will decay over time...
We'll see what happens :)
Thanks
-Vincent
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
10:33 a.m.
On Jul 29, 2013, at 10:11 AM, Marius Dumitru Florea <mariusdumitru.florea(a)xwiki.com>
wrote:
On Sat, Jul 27, 2013 at 5:19 PM, Vincent Massol
<vincent(a)massol.net> wrote:
Yes but as I said, projects that don't mandate comments don't have them, it's
as simple as that… Except of course for some conscientious developers; the risk being that
after some time they get bored and angry that they are the only ones doing it… ;)
Now private fields are not so bad, it just means that over time we'll probably see
less and less comments on private fields.
It's good to try new stuff though so I'm changing my vote to +0 not because I
think it's a good idea but because I'm interested in the experiment ;)
Thanks
-Vincent
Hi,
On Jul 27, 2013, at 3:48 PM, Sergiu Dumitriu <sergiu(a)xwiki.com> wrote:
Yes, for the repetitiveness, I've been using @see elements in all my code so that
only the getter is documented.
These are bad comments obviously… FTR I had put a small javadoc guide with some example
at:
http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HJavadocBestPra…
A good comment IMO is one that doesn't only explain what it represents but why
it's there and that shows an example when the data is untyped. For example:
/**
* The last person who made a modification to any part of this document (content,
objects, etc). Note that this is different from the creator who is the person who first
created the document. Example of author: "XWiki.Admin".
*/
private String author;
Suddenly it becomes interesting:
- we know it's about the last person who made a modification to any part of the
document which was not clear from the field (and it'll explain the difference with
contentAuthor too).
- we have an example showing what an author string looks like (of course using a
DocumentReference is even better since it's typed and clearly represents what is an
author)
With DocumentReference:
/**
* The last person who made a modification to any part of this document (content,
objects, etc). Note that it points to a reference to that author's document
representing it since we currently don't have a User object to represent a User.
*/
private DocumentReference author;
Future:
/**
* The last person who made a modification to any part of this document (content,
objects, etc).
*/
private User lastAuthor;
For this last example the comment becomes slightly less useful than in the previous
examples but it's still useful IMO.
On 07/26/2013 04:47 PM, Caleb James DeLisle
wrote:
> Hi,
> To promote contribution and encourage code brevity, I would like to remove
> the rule that we fail the build over a missing javadoc on a non-public
> field.
>
> It's important to understand, this is *not* about encouraging developers
> to skimp on documentation!
In practice it is (as can be demonstrated by the state of the oldcore when we started
working on it back in 2005) :)
> There are obvious cases such as
'logger' where the role of the field is
> blatantly clear and forced documentation is at best useless and at worst
> counterproductive because it creates an information overload for the code
> reader and hides the comments which the author really wanted to be seen.
Yes logger is a good example of a field for which it's hard to write an intelligent
comment ;)
+1 for
dropping this rule
+1. The best rule about commenting code is that comments should only say
what the code can't. Sometimes it's hard to come up with a good
non-repetitive comment like:
/** The author of the document. */
private DocumentReference author;
/**
* Get the author of the document.
* @return the author of the document
*/
public DocumentReference getAuthor(){...}
/**
* Set the author of the document.
* @param author the new author of the document to set
*/
public void setAuthor(DocumentReference author){…} Since most of our code is now components, we must
continue to thoroughly
document all our APIs (roles), but internal implementation details are
better documented by inline comments that actually explain tricky points
in the code, instead of reexplaining parameter names that should already
have Understandable Names.
I'm -0 but I'll follow the majority.
It's not because it's hard to write good comments that we shouldn't do it…
Obviously there are cases when it's really hard to find a good comment (like the
logger for example) but you can be sure that not mandating comments will not make them
automagically appear even for harder to understand cases.
Sure, but at the same time mandating comments on private fields
doesn't imply we are all going to write useful comments. So I'm +1. Thanks,
Marius
> We can only hope that all the xwiki devs have by now been trained enough to write
javadoc comments with our past strategy that they'll continue to write them wherever
needed but even that will decay over time...
>
> We'll see what happens :)
>
> Thanks
> -Vincent
31 Jul
31 Jul
12:01 a.m.
New subject: [xwiki-devs] [VOTE] Relax checkstyle rule about javadoc on non-public class members.
Results:
5 +1
1 +0
0 -1
The suggestion of repealing a rule leads people to think of the worst
possible outcome, hence the immortality of even the most ridiculous
legal prohibitions. Despite the fact that a single committer could
have killed this vote, we unanimously agreed to do something a little
crazy and for that I am proud.
In a year I'll review this change and report back on it's effectiveness.
Hold me to it.
Thanks,
Caleb
On 07/26/2013 04:47 PM, Caleb James DeLisle wrote:
Hi,
To promote contribution and encourage code brevity, I would like to remove
the rule that we fail the build over a missing javadoc on a non-public
field.
It's important to understand, this is *not* about encouraging developers
to skimp on documentation!
There are obvious cases such as 'logger' where the role of the field is
blatantly clear and forced documentation is at best useless and at worst
counterproductive because it creates an information overload for the code
reader and hides the comments which the author really wanted to be seen.
+1 for dropping this rule
Thanks,
Caleb
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
4066
days inactive
4070
days old
8 comments
6 participants
participants (6)
-
Caleb James DeLisle -
Denis Gervalle -
Marius Dumitru Florea -
Sergiu Dumitriu -
Thomas Mortagne -
Vincent Massol