Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
On Thu, Dec 4, 2014 at 11:28 AM, Robert O'Callahan rob...@ocallahan.org wrote: On Thu, Dec 4, 2014 at 12:35 PM, Seth Fowler s...@mozilla.com wrote: I’d like to change the coding style guide to let us make out-params more obvious by using an ‘o’ prefix for their name instead of an ‘a’. For example, nsresult Modify(int aCount, size_t aSize, char* oResult); This will make it clear just from the declaration of a function or method which parameters are out-params. XPCOM requires us to use out-params a lot, and I’ve found that determining when it’s happening often requires me to look at the code for the method, especially since we frequently use pointer arguments for efficiency or because the argument is optional. Seems to me like a substantial gain in readability for little or no cost. I think this would be a slight improvement but the place where I really want out-parameters to be visible is at the caller, not the callee. I guess, to make it clear at caller side, and force the compiler to check it as much as possible, the best way would be having a template class e.g. Out which holds a reference to the target variable, and giving it proper implicit conversion, e.g. OutT can be implicitly converted to T but not inversely. With that, I guess we can use it directly in new code, and the usage in caller will be compatible with the existing functions. Might be something like this: https://gist.github.com/upsuper/322bde839f3552ff7e3b - Xidorn ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
On Sat, Dec 6, 2014 at 1:31 AM, Botond Ballo bba...@mozilla.com wrote: In APZ code, we've been using the prefix 'aOut' for out-parameters. This keeps them consistent with the general rule of 'a' for arguments while identifying out-parameters with a convention. This is what I'm accustomed to as well. I prefer it because it's less cryptic -- the fewer magical one-letter prefixes the better. It is longer, but that doesn't bother me. It also has the bonus of not being overtly inconsistent with existing code, and being used already in some code. (editor uses it a lot.) ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
On Dec 4, 2014, at 11:28 AM, Robert O'Callahan rob...@ocallahan.org wrote: I think this would be a slight improvement but the place where I really want out-parameters to be visible is at the caller, not the callee. Agreed! The simplest way to achieve that in C++, though, is to use pointer arguments (so the ‘' operator will generally get used at the callsite). The problem is that since pointers are overloaded and have several other uses besides out-params, the intention isn’t clear at the method definition. (And for longer methods, it can even be unclear in the implementation code.) The ‘o’ prefix nicely complements the practice of using ‘’ at the callsite, so we get clarity at the caller and the callee. I think that the cost of introducing this convention and dealing with the inconsistency of it being incompletely applied across the codebase for the foreseeable future probably outweighs the benefits. Well, converting all existing code to use this convention overnight definitely wouldn’t be worth it. And just adding this to the style guide will give us very little benefit *right now*. But I think if we add this to the coding style guide and convert things gradually in a pragmatic fashion - when we write new code, when we touch old code that doesn’t use the convention, and perhaps when we encounter an unclear method definition in the course of our work - a year or two down the road it may be common enough that we get significant benefits from the change. - Seth ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
On Dec 4, 2014, at 11:02 AM, Eric Rescorla e...@rtfm.com wrote: In contrast, Seth's suggestion would be an extremely clear indication that a parameter is an outparam. Yes, and because it's just a convention and not compiler enforced it can also be wrong. I don’t know of any realistic, usable way we could enforce this via the compiler in C++, though. I agree that in theory the ‘o’ prefix could be wrong, but code review provides us some degree of protection against these kinds of issues, and I don’t think we should let the perfect be the enemy of the good here. (After all, in theory the ‘a’ prefix we use for indicating arguments could be wrong, but in practice I have never seen a problem with that.) - Seth ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
On Fri, Dec 5, 2014 at 12:08 PM, Seth Fowler s...@mozilla.com wrote: Well, converting all existing code to use this convention overnight definitely wouldn’t be worth it. And just adding this to the style guide will give us very little benefit *right now*. But I think if we add this to the coding style guide and convert things gradually in a pragmatic fashion - when we write new code, when we touch old code that doesn’t use the convention, and perhaps when we encounter an unclear method definition in the course of our work - a year or two down the road it may be common enough that we get significant benefits from the change. The interregnum period creates confusion in the minds of developers, who for example may not know whether to use o per the style guide or a to be consistent with surrounding code. This is a cost. I think in the past we've underestimated the costs of incomplete transitions in coding style. Rob -- oIo otoeololo oyooouo otohoaoto oaonoyooonoeo owohooo oioso oaonogoroyo owoiotoho oao oboroootohoeoro oooro osoiosotoeoro owoiololo oboeo osouobojoeocoto otooo ojouodogomoeonoto.o oAogoaoiono,o oaonoyooonoeo owohooo osoaoyoso otooo oao oboroootohoeoro oooro osoiosotoeoro,o o‘oRoaocoao,o’o oioso oaonosowoeoroaoboloeo otooo otohoeo ocooouoroto.o oAonodo oaonoyooonoeo owohooo osoaoyoso,o o‘oYooouo ofolo!o’o owoiololo oboeo oiono odoaonogoeoro ooofo otohoeo ofoioroeo ooofo ohoeololo. ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
You sometimes see comments for this, e.g. int foo(int aX, /* out */ char* aS); If we recommended/required this, it might make the interregnum period problem smaller? Nick On Fri, Dec 5, 2014 at 1:31 PM, Robert O'Callahan rob...@ocallahan.org wrote: On Fri, Dec 5, 2014 at 12:08 PM, Seth Fowler s...@mozilla.com wrote: Well, converting all existing code to use this convention overnight definitely wouldn’t be worth it. And just adding this to the style guide will give us very little benefit *right now*. But I think if we add this to the coding style guide and convert things gradually in a pragmatic fashion - when we write new code, when we touch old code that doesn’t use the convention, and perhaps when we encounter an unclear method definition in the course of our work - a year or two down the road it may be common enough that we get significant benefits from the change. The interregnum period creates confusion in the minds of developers, who for example may not know whether to use o per the style guide or a to be consistent with surrounding code. This is a cost. I think in the past we've underestimated the costs of incomplete transitions in coding style. Rob -- oIo otoeololo oyooouo otohoaoto oaonoyooonoeo owohooo oioso oaonogoroyo owoiotoho oao oboroootohoeoro oooro osoiosotoeoro owoiololo oboeo osouobojoeocoto otooo ojouodogomoeonoto.o oAogoaoiono,o oaonoyooonoeo owohooo osoaoyoso otooo oao oboroootohoeoro oooro osoiosotoeoro,o o‘oRoaocoao,o’o oioso oaonosowoeoroaoboloeo otooo otohoeo ocooouoroto.o oAonodo oaonoyooonoeo owohooo osoaoyoso,o o‘oYooouo ofolo!o’o owoiololo oboeo oiono odoaonogoeoro ooofo otohoeo ofoioroeo ooofo ohoeololo. ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
In APZ code, we've been using the prefix 'aOut' for out-parameters. This keeps them consistent with the general rule of 'a' for arguments while identifying out-parameters with a convention. Cheers, Botond - Original Message - From: Nicholas Nethercote n.netherc...@gmail.com To: Robert O'Callahan rob...@ocallahan.org Cc: dev-platform dev-platform@lists.mozilla.org, Seth Fowler s...@mozilla.com Sent: Friday, December 5, 2014 5:10:09 PM Subject: Re: Proposal: Change the coding style guide to allow an 'o' prefix toindicate out-params You sometimes see comments for this, e.g. int foo(int aX, /* out */ char* aS); If we recommended/required this, it might make the interregnum period problem smaller? Nick On Fri, Dec 5, 2014 at 1:31 PM, Robert O'Callahan rob...@ocallahan.org wrote: On Fri, Dec 5, 2014 at 12:08 PM, Seth Fowler s...@mozilla.com wrote: Well, converting all existing code to use this convention overnight definitely wouldn’t be worth it. And just adding this to the style guide will give us very little benefit *right now*. But I think if we add this to the coding style guide and convert things gradually in a pragmatic fashion - when we write new code, when we touch old code that doesn’t use the convention, and perhaps when we encounter an unclear method definition in the course of our work - a year or two down the road it may be common enough that we get significant benefits from the change. The interregnum period creates confusion in the minds of developers, who for example may not know whether to use o per the style guide or a to be consistent with surrounding code. This is a cost. I think in the past we've underestimated the costs of incomplete transitions in coding style. Rob -- oIo otoeololo oyooouo otohoaoto oaonoyooonoeo owohooo oioso oaonogoroyo owoiotoho oao oboroootohoeoro oooro osoiosotoeoro owoiololo oboeo osouobojoeocoto otooo ojouodogomoeonoto.o oAogoaoiono,o oaonoyooonoeo owohooo osoaoyoso otooo oao oboroootohoeoro oooro osoiosotoeoro,o o‘oRoaocoao,o’o oioso oaonosowoeoroaoboloeo otooo otohoeo ocooouoroto.o oAonodo oaonoyooonoeo owohooo osoaoyoso,o o‘oYooouo ofolo!o’o owoiololo oboeo oiono odoaonogoeoro ooofo otohoeo ofoioroeo ooofo ohoeololo. ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
I’d like to change the coding style guide to let us make out-params more obvious by using an ‘o’ prefix for their name instead of an ‘a’. For example, nsresult Modify(int aCount, size_t aSize, char* oResult); This will make it clear just from the declaration of a function or method which parameters are out-params. XPCOM requires us to use out-params a lot, and I’ve found that determining when it’s happening often requires me to look at the code for the method, especially since we frequently use pointer arguments for efficiency or because the argument is optional. Seems to me like a substantial gain in readability for little or no cost. - Seth ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
On Thu, Dec 4, 2014 at 10:35 AM, Seth Fowler s...@mozilla.com wrote: I’d like to change the coding style guide to let us make out-params more obvious by using an ‘o’ prefix for their name instead of an ‘a’. For example, nsresult Modify(int aCount, size_t aSize, char* oResult); This will make it clear just from the declaration of a function or method which parameters are out-params. XPCOM requires us to use out-params a lot, and I’ve found that determining when it’s happening often requires me to look at the code for the method, especially since we frequently use pointer arguments for efficiency or because the argument is optional. Seems to me like a substantial gain in readability for little or no cost. What fraction of these cases can't be distinguished by making non-out ref/pointer parameters const? -Ekr ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
On Fri, Dec 5, 2014 at 5:41 AM, Eric Rescorla e...@rtfm.com wrote: I’d like to change the coding style guide to let us make out-params more obvious by using an ‘o’ prefix for their name instead of an ‘a’. For example, What fraction of these cases can't be distinguished by making non-out ref/pointer parameters const? The non-const-ness of a parameter is a weak, indirect indication that it's an outparam, and one that is probably not consistent across the codebase. I bet we have bazillions of non-const, non-outparams. In contrast, Seth's suggestion would be an extremely clear indication that a parameter is an outparam. Nick ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
On Thursday 2014-12-04 10:35 -0800, Seth Fowler wrote: I’d like to change the coding style guide to let us make out-params more obvious by using an ‘o’ prefix for their name instead of an ‘a’. For example, nsresult Modify(int aCount, size_t aSize, char* oResult); This will make it clear just from the declaration of a function or method which parameters are out-params. XPCOM requires us to use out-params a lot, and I’ve found that determining when it’s happening often requires me to look at the code for the method, especially since we frequently use pointer arguments for efficiency or because the argument is optional. Seems to me like a substantial gain in readability for little or no cost. If we adopt this convention, should we also have a convention for an in-out param? (If so, what?) -David -- 턞 L. David Baron http://dbaron.org/ 턂 턢 Mozilla https://www.mozilla.org/ 턂 Before I built a wall I'd ask to know What I was walling in or walling out, And to whom I was like to give offense. - Robert Frost, Mending Wall (1914) signature.asc Description: Digital signature ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
I typically append Out to these parameter names. The o prefix would be more concise. +1 Thanks! Ben - Original Message - From: Seth Fowler s...@mozilla.com To: dev-platform dev-platform@lists.mozilla.org Sent: Thursday, December 4, 2014 1:35:06 PM Subject: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params I’d like to change the coding style guide to let us make out-params more obvious by using an ‘o’ prefix for their name instead of an ‘a’. For example, nsresult Modify(int aCount, size_t aSize, char* oResult); This will make it clear just from the declaration of a function or method which parameters are out-params. XPCOM requires us to use out-params a lot, and I’ve found that determining when it’s happening often requires me to look at the code for the method, especially since we frequently use pointer arguments for efficiency or because the argument is optional. Seems to me like a substantial gain in readability for little or no cost. - Seth ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
On Thu, Dec 4, 2014 at 10:51 AM, Nicholas Nethercote n.netherc...@gmail.com wrote: On Fri, Dec 5, 2014 at 5:41 AM, Eric Rescorla e...@rtfm.com wrote: I’d like to change the coding style guide to let us make out-params more obvious by using an ‘o’ prefix for their name instead of an ‘a’. For example, What fraction of these cases can't be distinguished by making non-out ref/pointer parameters const? The non-const-ness of a parameter is a weak, indirect indication that it's an outparam, and one that is probably not consistent across the codebase. I bet we have bazillions of non-const, non-outparams. Yes, that's true, but we would continue to have bazillions of outparams which will not be named oFoo, so the absence of the o doesn't tell you it's not an outparam (and this will be the dominant case for the foreseeable future). In contrast, Seth's suggestion would be an extremely clear indication that a parameter is an outparam. Yes, and because it's just a convention and not compiler enforced it can also be wrong. -Ekr ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
On 2014-12-04, at 10:51, Nicholas Nethercote n.netherc...@gmail.com wrote: What fraction of these cases can't be distinguished by making non-out ref/pointer parameters const? The non-const-ness of a parameter is a weak, indirect indication that it's an outparam, and one that is probably not consistent across the codebase. I bet we have bazillions of non-const, non-outparams. ekr’s suggestion is to let the type system provide that indication. The purported value of hungarian notation is that is attaches critical contextual information to the name. That isn’t generally necessary at the call site in a function or class of manageable size. I would personally rather not annotate variables based on provenance altogether, because I don’t find that particularly useful. The other aspect is caller documentation. There is an ambiguity between “I need to play with this” and “I will use this to give you something back”, but as dbaron observes, even this isn’t enough to cover all the available options. Other languages address the documentation concern by using the type system to enforce out- or in-out- ness of an argument, which does have other advantages. Without creating a new - probably largely pointless - template, we don’t really have that option. ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Proposal: Change the coding style guide to allow an 'o' prefix to indicate out-params
On Thu, Dec 4, 2014 at 12:35 PM, Seth Fowler s...@mozilla.com wrote: I’d like to change the coding style guide to let us make out-params more obvious by using an ‘o’ prefix for their name instead of an ‘a’. For example, nsresult Modify(int aCount, size_t aSize, char* oResult); This will make it clear just from the declaration of a function or method which parameters are out-params. XPCOM requires us to use out-params a lot, and I’ve found that determining when it’s happening often requires me to look at the code for the method, especially since we frequently use pointer arguments for efficiency or because the argument is optional. Seems to me like a substantial gain in readability for little or no cost. I think this would be a slight improvement but the place where I really want out-parameters to be visible is at the caller, not the callee. I think that the cost of introducing this convention and dealing with the inconsistency of it being incompletely applied across the codebase for the foreseeable future probably outweighs the benefits. Rob -- oIo otoeololo oyooouo otohoaoto oaonoyooonoeo owohooo oioso oaonogoroyo owoiotoho oao oboroootohoeoro oooro osoiosotoeoro owoiololo oboeo osouobojoeocoto otooo ojouodogomoeonoto.o oAogoaoiono,o oaonoyooonoeo owohooo osoaoyoso otooo oao oboroootohoeoro oooro osoiosotoeoro,o o‘oRoaocoao,o’o oioso oaonosowoeoroaoboloeo otooo otohoeo ocooouoroto.o oAonodo oaonoyooonoeo owohooo osoaoyoso,o o‘oYooouo ofolo!o’o owoiololo oboeo oiono odoaonogoeoro ooofo otohoeo ofoioroeo ooofo ohoeololo. ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
