One more point on this. "Consistency" as some sort of independent goal by itself has no place in open source software. We need to keep our eyes on the prize, which is making it easy for users to understand and use the software and for volunteers to get involved. To the extent that consistent API and doco design contributes to these goals, great. But arcane rules or excessively complicated APIs that make it harder for people to use the software and get involved are to be avoided.
Phil On Nov 25, 2011, at 2:13 AM, Sébastien Brisard <[email protected]> wrote: > Hi, > here are a few questions about the implicit rules in use in CM for > formatting Javadoc comments, that I've wanted to post for a long time. > Since I'm now reviewing other people's patches, I think it's high time > to clear these questions up. If I'm not mistaken, > (1) every @param tag should start with a capital letter and end with a period > (2) every @return tag should end with a period > When I first submitted a patch (and it was corrected accordingly), I > was a little surprised, since it is in contradiction with conventions > [1] which I (and obviously, others) was used to > (3) Regarding @param tags: "The description begins with a lowercase > letter if it is a phrase (contains no verb), or an uppercase letter if > it is a sentence. End the phrase with a period only if another phrase > or sentence follows it." > (4) Regarding @return tags: "Use the same capitalization and > punctuation as you used in @param." > > I'm not saying these conventions are good/bad. However, they are > consistent with automatic tags (eg "Specified by", which do *not* end > with a period). Besides, I think rules (1) and (2) are not > consistently enforced throughout CM (to take but one example: I > constantly find myself reverting to my old habits...) and so I'm > reluctant to correct other people's work to try and comply with rules > I'm not absolutely sure everyone agrees about. > > I think it would be nice if everyone who is particularly attached to > an unstated rule just states it. We could then gather all those rules > in the Developers resources section of the website (I can do that, > please just write up the list in this thread). This would allow us, > and others, to refer to this document in order to ensure homogeneity > throughout the whole library. > > What do you think? Best regards, > Sébastien > > [1] > http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#tag > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
