commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From S├ębastien Brisard <sebastien.bris...@m4x.org>
Subject Re: [math] Formatting
Date Fri, 24 Aug 2012 02:37:41 GMT
Hi,
the idea is *not* to come up with dozens of impossible, picky and
useless rules, but a few rules which we do care about, are easily
enforced, and ensure some kind of consistency.

Of course, consistency in code formatting is more easily enforced than
in comments formatting. But I have to say that, like Gilles, I like to
observe *some kind* of consistency in the javadoc of a library, both
as a user and as a developer. I agree with Gilles, it's just like
reading an article. Poorly formatted papers (or presentations) just
hurt my eyes, regardless of the content.

I understand we may have different views on this point, and I agree
that the essential point is certainly that the comment is
understandable (even, as Churchill would say, by native english
speakers!), and useful. I think it's worth having a go coming up with
a limited set of additional rules.

By the way, if you browse through the whole javadoc of CM, you *do*
observe a kind of consistency [1]. So, whether written or not, we *do*
follow some rules.

Anyway, what I proposed was not to set THE LAW, but rather, to build a
list of guidelines, to be discussed with everyone.

Best regards,
S├ębastien

[1] although some recent discussions have shown that *I* break some of
these unstated rules... I will do my best to improve on this side. I
think that's proof that written guidelines could help.


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message