Igniters,
I want to discuss the appendix of our code-style: https://cwiki.apache.org/confluence/display/IGNITE/Abbreviation+Rules. First of all, there is no any mention that it is a mandatory part. Secondly, some of them are very unintuitive and even misleading. For example, cp. In current realization, it could mean not only copy but checkpoint. Other example, proto... Would you get that it is protocol? Thirdly, the recommended plugin highlights even parts of multiword names. It provokes to used creepy names as locCpPartitionsInProgress, needCpPartitions and so on. So, I want to start a discussion for 1. revising the list of abbreviations, 2. stop using them for multi-word names, 3. and make them not mandatory at all (what it is actually already true, because of no any mention in the main code-style article). |
+1
I'm for long and descriptive names over short and counterintuitive. I think, abbreviations shouldn't be mandatory, as they often obscure the meaning of used names. One-letter abbreviations should be removed from the list at all. When I see a variable *c*, I can't tell, whether it's a char, collection, callable or a closure, even if I remember the rules by heart. Denis вт, 16 окт. 2018 г. в 19:01, Eduard Shangareev <[hidden email] >: > Igniters, > > I want to discuss the appendix of our code-style: > https://cwiki.apache.org/confluence/display/IGNITE/Abbreviation+Rules. > > First of all, there is no any mention that it is a mandatory part. > > Secondly, some of them are very unintuitive and even misleading. For > example, cp. In current realization, it could mean not only copy but > checkpoint. Other example, proto... Would you get that it is protocol? > > Thirdly, the recommended plugin highlights even parts of multiword names. > It provokes to used creepy names as > locCpPartitionsInProgress, needCpPartitions and so on. > > So, I want to start a discussion for > 1. revising the list of abbreviations, > 2. stop using them for multi-word names, > 3. and make them not mandatory at all (what it is actually already true, > because of no any mention in the main code-style article). > |
In reply to this post by Eduard Shangareev
Eduard,
+1 for that topic. I don't see any reasons to use these abbreviations at all and vote to deprecate them. If anybody can explain why we still need them (less number of letters in variable names is not an argument) we can discuss and revisit the current list. From my side of view, these abbreviations just worsen readability of code and don't give any major benefits. вт, 16 окт. 2018 г. в 19:01, Eduard Shangareev <[hidden email] >: > Igniters, > > I want to discuss the appendix of our code-style: > https://cwiki.apache.org/confluence/display/IGNITE/Abbreviation+Rules. > > First of all, there is no any mention that it is a mandatory part. > > Secondly, some of them are very unintuitive and even misleading. For > example, cp. In current realization, it could mean not only copy but > checkpoint. Other example, proto... Would you get that it is protocol? > > Thirdly, the recommended plugin highlights even parts of multiword names. > It provokes to used creepy names as > locCpPartitionsInProgress, needCpPartitions and so on. > > So, I want to start a discussion for > 1. revising the list of abbreviations, > 2. stop using them for multi-word names, > 3. and make them not mandatory at all (what it is actually already true, > because of no any mention in the main code-style article). > |
In reply to this post by Eduard Shangareev
+1
Eduard, I totally agree with you that it is misleading. I believe developer/reviewer able to choose convenient name in each particular case by themself. In my opinion abbreviation should be not mandatory. -- Best regards, Anton Kalashnikov 16.10.2018, 19:01, "Eduard Shangareev" <[hidden email]>: > Igniters, > > I want to discuss the appendix of our code-style: > https://cwiki.apache.org/confluence/display/IGNITE/Abbreviation+Rules. > > First of all, there is no any mention that it is a mandatory part. > > Secondly, some of them are very unintuitive and even misleading. For > example, cp. In current realization, it could mean not only copy but > checkpoint. Other example, proto... Would you get that it is protocol? > > Thirdly, the recommended plugin highlights even parts of multiword names. > It provokes to used creepy names as > locCpPartitionsInProgress, needCpPartitions and so on. > > So, I want to start a discussion for > 1. revising the list of abbreviations, > 2. stop using them for multi-word names, > 3. and make them not mandatory at all (what it is actually already true, > because of no any mention in the main code-style article). |
In reply to this post by Eduard Shangareev
+ for all three.
I got used to seeing `cctx` and `ccfg` all over the place, but I remember the sorrow of seeing all of that the first time. I guess it’s nothing but a Stockholm syndrome now and I’m willing to cure myself :) Stan From: Eduard Shangareev Sent: 16 октября 2018 г. 19:01 To: [hidden email] Subject: Abbreviation code-style requirement. Igniters, I want to discuss the appendix of our code-style: https://cwiki.apache.org/confluence/display/IGNITE/Abbreviation+Rules. First of all, there is no any mention that it is a mandatory part. Secondly, some of them are very unintuitive and even misleading. For example, cp. In current realization, it could mean not only copy but checkpoint. Other example, proto... Would you get that it is protocol? Thirdly, the recommended plugin highlights even parts of multiword names. It provokes to used creepy names as locCpPartitionsInProgress, needCpPartitions and so on. So, I want to start a discussion for 1. revising the list of abbreviations, 2. stop using them for multi-word names, 3. and make them not mandatory at all (what it is actually already true, because of no any mention in the main code-style article). |
Ed, and All.
I'm "+1" for "revising the list of abbreviations," How about to have only 5-10 nice (proven) abbreviations and let developers to name variables using common sense? So, I want to start a discussion for > 1. revising the list of abbreviations, > 2. stop using them for multi-word names, > 3. and make them not mandatory at all (what it is actually already true, > because of no any mention in the main code-style article). > > -- Alexey Kuznetsov |
In reply to this post by Eduard Shangareev
+ 1
I dislike the current list of abbreviations. It gives me a pain to support code with unclear variables naming, also I agree that we should avoid crazy Java camel long naming like FactoryBuildingCrazyAffinityCallerForComibingInSpace but instead that we make shorter clear concepts like /counter/, /vertex/, /collection/ and etc -- Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/ |
+ 1
But, I think that we must leave abbreviations for common words with single meaning. For example, group -> grp, transaction -> tx, context -> ctx. ср, 17 окт. 2018 г. в 12:46, Alexey Zinoviev <[hidden email]>: > + 1 > I dislike the current list of abbreviations. It gives me a pain to support > code with unclear variables naming, also I agree that we should avoid crazy > Java camel long naming like > FactoryBuildingCrazyAffinityCallerForComibingInSpace but instead that we > make shorter clear concepts like /counter/, /vertex/, /collection/ and etc > > > > -- > Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/ > -- BR, Sergey Antonov |
+ 1 from me to make abbreviations optional.
On Wed, Oct 17, 2018 at 1:00 PM Sergey Antonov <[hidden email]> wrote: > + 1 > > But, I think that we must leave abbreviations for common words with single > meaning. For example, group -> grp, transaction -> tx, context -> ctx. > > ср, 17 окт. 2018 г. в 12:46, Alexey Zinoviev <[hidden email]>: > > > + 1 > > I dislike the current list of abbreviations. It gives me a pain to > support > > code with unclear variables naming, also I agree that we should avoid > crazy > > Java camel long naming like > > FactoryBuildingCrazyAffinityCallerForComibingInSpace but instead that we > > make shorter clear concepts like /counter/, /vertex/, /collection/ and > etc > > > > > > > > -- > > Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/ > > > > > -- > BR, Sergey Antonov > -- Best regards, Ilya |
+1 to
> leave abbreviations for common words with single meaning. For example, group -> grp, transaction -> tx, context -> ctx. And optional for the multi-words. ср, 17 окт. 2018 г. в 14:54, Ilya Lantukh <[hidden email]>: > + 1 from me to make abbreviations optional. > > On Wed, Oct 17, 2018 at 1:00 PM Sergey Antonov <[hidden email]> > wrote: > > > + 1 > > > > But, I think that we must leave abbreviations for common words with > single > > meaning. For example, group -> grp, transaction -> tx, context -> ctx. > > > > ср, 17 окт. 2018 г. в 12:46, Alexey Zinoviev <[hidden email]>: > > > > > + 1 > > > I dislike the current list of abbreviations. It gives me a pain to > > support > > > code with unclear variables naming, also I agree that we should avoid > > crazy > > > Java camel long naming like > > > FactoryBuildingCrazyAffinityCallerForComibingInSpace but instead that > we > > > make shorter clear concepts like /counter/, /vertex/, /collection/ and > > etc > > > > > > > > > > > > -- > > > Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/ > > > > > > > > > -- > > BR, Sergey Antonov > > > > > -- > Best regards, > Ilya > |
In reply to this post by Eduard Shangareev
+1.
I think we should use longer names when possible, even for a small pieces of code, cause this makes code self descriptive. I can agree that for really small and obvious methods we can use short words like "context", but not confusing abbreviated one. вт, 16 окт. 2018 г., 19:01 Eduard Shangareev <[hidden email]>: > Igniters, > > I want to discuss the appendix of our code-style: > https://cwiki.apache.org/confluence/display/IGNITE/Abbreviation+Rules. > > First of all, there is no any mention that it is a mandatory part. > > Secondly, some of them are very unintuitive and even misleading. For > example, cp. In current realization, it could mean not only copy but > checkpoint. Other example, proto... Would you get that it is protocol? > > Thirdly, the recommended plugin highlights even parts of multiword names. > It provokes to used creepy names as > locCpPartitionsInProgress, needCpPartitions and so on. > > So, I want to start a discussion for > 1. revising the list of abbreviations, > 2. stop using them for multi-word names, > 3. and make them not mandatory at all (what it is actually already true, > because of no any mention in the main code-style article). > |
In reply to this post by Eduard Shangareev
+1 for all proposals.
|
+1 for proposal 3.
1. I'm not sure we need to revisit all abbreviations as a lot of people get used to it. 2. I'm not sure multiword is always need to be fully named, sometimes it may be ok to abbreviate. 3. But I agree with abbreviations should not be mandatory. Abbreviated and short names like i,j,cp and etc. are good for simple methods and code blocks; for a fast demonstration of some idea, but for complex enterprise level software it can hide meaning instead of clearly showing it. As a next step, I would like to propose to contribute an option to disable abbreviation requirements for some cases in ignite-abbrev-plugin. сб, 20 окт. 2018 г. в 10:47, Zhenya <[hidden email]>: > +1 for all proposals. > |
Hi all,
I also think that abbreviations should not be mandatory (point 3). But what I am worrying about is a conflict resolution between a patch submitter and a reviewer. How to come to an agreement when one side is strictly for and another side is strictly against using abbreviations in some concrete case? вс, 21 окт. 2018 г. в 11:34, Dmitriy Pavlov <[hidden email]>: > +1 for proposal 3. > > 1. I'm not sure we need to revisit all abbreviations as a lot of people get > used to it. > 2. I'm not sure multiword is always need to be fully named, sometimes it > may be ok to abbreviate. > 3. But I agree with abbreviations should not be mandatory. > > Abbreviated and short names like i,j,cp and etc. are good for simple > methods and code blocks; for a fast demonstration of some idea, but for > complex enterprise level software it can hide meaning instead of clearly > showing it. > > As a next step, I would like to propose to contribute an option to disable > abbreviation requirements for some cases in ignite-abbrev-plugin. > > сб, 20 окт. 2018 г. в 10:47, Zhenya <[hidden email]>: > > > +1 for all proposals. > > > -- Best regards, Ivan Pavlukhin |
Igniters,
I think it's easy to disable the code style abbreviation plugin option by switching off the checkbox on - File | Settings | Inspections | Apache Ignite | Incorrect Java abbreviation usage. +1 to make abbreviation not mandatory, but I'd like to keep it for common variable names like `context = ctx`. On Mon, 22 Oct 2018 at 14:05 Павлухин Иван <[hidden email]> wrote: > Hi all, > > I also think that abbreviations should not be mandatory (point 3). > But what I am worrying about is a conflict resolution between a patch > submitter and a reviewer. > How to come to an agreement when one side is strictly for and another side > is strictly against > using abbreviations in some concrete case? > > вс, 21 окт. 2018 г. в 11:34, Dmitriy Pavlov <[hidden email]>: > > > +1 for proposal 3. > > > > 1. I'm not sure we need to revisit all abbreviations as a lot of people > get > > used to it. > > 2. I'm not sure multiword is always need to be fully named, sometimes it > > may be ok to abbreviate. > > 3. But I agree with abbreviations should not be mandatory. > > > > Abbreviated and short names like i,j,cp and etc. are good for simple > > methods and code blocks; for a fast demonstration of some idea, but for > > complex enterprise level software it can hide meaning instead of clearly > > showing it. > > > > As a next step, I would like to propose to contribute an option to > disable > > abbreviation requirements for some cases in ignite-abbrev-plugin. > > > > сб, 20 окт. 2018 г. в 10:47, Zhenya <[hidden email]>: > > > > > +1 for all proposals. > > > > > > > > -- > Best regards, > Ivan Pavlukhin > -- Maxim Muzafarov |
Hi Ivan
if by conflict we mean arguing and fighting it is definitely should be avoided, it never helps the community. But if we mean different opinions on details (variable namings, method structure, etc), such different views are unavoidable and I find it is perfectly ok that people with different background have different views. The paramount thing here if we can solve such conflicts with a positive outcome for all community and for the codebase. The good friend of mine reminded me some time ago that we all have a common goal here: make the community bigger and this project better. If we always remember that we are connected by a common interest but we admit each contributor may have different preferences in coding and probably different opinion. We may build up consensus sharing our arguments if it is really needed, or these different opinions/priorities/preferences may co-exist. In a particular case, if reviewer's concerns are not major, another reviewer can agree with your proposal. So it should be always considered case-by-case, there is no silver bullet here. Sincerely, Dmitriy Pavlov вт, 23 окт. 2018 г., 11:32 Maxim Muzafarov <[hidden email]>: > Igniters, > > I think it's easy to disable the code style abbreviation plugin option by > switching off > the checkbox on - File | Settings | Inspections | Apache Ignite | Incorrect > Java abbreviation usage. > > +1 to make abbreviation not mandatory, but I'd like to keep it for common > variable names like `context = ctx`. > > On Mon, 22 Oct 2018 at 14:05 Павлухин Иван <[hidden email]> wrote: > > > Hi all, > > > > I also think that abbreviations should not be mandatory (point 3). > > But what I am worrying about is a conflict resolution between a patch > > submitter and a reviewer. > > How to come to an agreement when one side is strictly for and another > side > > is strictly against > > using abbreviations in some concrete case? > > > > вс, 21 окт. 2018 г. в 11:34, Dmitriy Pavlov <[hidden email]>: > > > > > +1 for proposal 3. > > > > > > 1. I'm not sure we need to revisit all abbreviations as a lot of people > > get > > > used to it. > > > 2. I'm not sure multiword is always need to be fully named, sometimes > it > > > may be ok to abbreviate. > > > 3. But I agree with abbreviations should not be mandatory. > > > > > > Abbreviated and short names like i,j,cp and etc. are good for simple > > > methods and code blocks; for a fast demonstration of some idea, but for > > > complex enterprise level software it can hide meaning instead of > clearly > > > showing it. > > > > > > As a next step, I would like to propose to contribute an option to > > disable > > > abbreviation requirements for some cases in ignite-abbrev-plugin. > > > > > > сб, 20 окт. 2018 г. в 10:47, Zhenya <[hidden email]>: > > > > > > > +1 for all proposals. > > > > > > > > > > > > > -- > > Best regards, > > Ivan Pavlukhin > > > -- > -- > Maxim Muzafarov > |
Igniters,
thank you for your feedback. I haven't seen any arguments against making abbreviation optional and not mandatory. So, could we update our wiki with code style to reflect our new vision on abbreviations? On Tue, Oct 23, 2018 at 2:01 PM Dmitriy Pavlov <[hidden email]> wrote: > Hi Ivan > > if by conflict we mean arguing and fighting it is definitely should be > avoided, it never helps the community. > > But if we mean different opinions on details (variable namings, method > structure, etc), such different views are unavoidable and I find it is > perfectly ok that people with different background have different views. > The paramount thing here if we can solve such conflicts with a positive > outcome for all community and for the codebase. > > The good friend of mine reminded me some time ago that we all have a common > goal here: make the community bigger and this project better. If we always > remember that we are connected by a common interest but we admit each > contributor may have different preferences in coding and probably different > opinion. We may build up consensus sharing our arguments if it is really > needed, or these different opinions/priorities/preferences may co-exist. > > In a particular case, if reviewer's concerns are not major, another > reviewer can agree with your proposal. So it should be always considered > case-by-case, there is no silver bullet here. > > Sincerely, > Dmitriy Pavlov > > вт, 23 окт. 2018 г., 11:32 Maxim Muzafarov <[hidden email]>: > > > Igniters, > > > > I think it's easy to disable the code style abbreviation plugin option by > > switching off > > the checkbox on - File | Settings | Inspections | Apache Ignite | > Incorrect > > Java abbreviation usage. > > > > +1 to make abbreviation not mandatory, but I'd like to keep it for common > > variable names like `context = ctx`. > > > > On Mon, 22 Oct 2018 at 14:05 Павлухин Иван <[hidden email]> wrote: > > > > > Hi all, > > > > > > I also think that abbreviations should not be mandatory (point 3). > > > But what I am worrying about is a conflict resolution between a patch > > > submitter and a reviewer. > > > How to come to an agreement when one side is strictly for and another > > side > > > is strictly against > > > using abbreviations in some concrete case? > > > > > > вс, 21 окт. 2018 г. в 11:34, Dmitriy Pavlov <[hidden email]>: > > > > > > > +1 for proposal 3. > > > > > > > > 1. I'm not sure we need to revisit all abbreviations as a lot of > people > > > get > > > > used to it. > > > > 2. I'm not sure multiword is always need to be fully named, sometimes > > it > > > > may be ok to abbreviate. > > > > 3. But I agree with abbreviations should not be mandatory. > > > > > > > > Abbreviated and short names like i,j,cp and etc. are good for simple > > > > methods and code blocks; for a fast demonstration of some idea, but > for > > > > complex enterprise level software it can hide meaning instead of > > clearly > > > > showing it. > > > > > > > > As a next step, I would like to propose to contribute an option to > > > disable > > > > abbreviation requirements for some cases in ignite-abbrev-plugin. > > > > > > > > сб, 20 окт. 2018 г. в 10:47, Zhenya <[hidden email]>: > > > > > > > > > +1 for all proposals. > > > > > > > > > > > > > > > > > > -- > > > Best regards, > > > Ivan Pavlukhin > > > > > -- > > -- > > Maxim Muzafarov > > > |
Hi Eduard, feel free to share your wiki ID, I could set up an edit
permissions. ср, 24 окт. 2018 г. в 14:18, Eduard Shangareev <[hidden email] >: > Igniters, > thank you for your feedback. > > I haven't seen any arguments against making abbreviation optional and not > mandatory. > So, could we update our wiki with code style to reflect our new vision on > abbreviations? > > On Tue, Oct 23, 2018 at 2:01 PM Dmitriy Pavlov <[hidden email]> > wrote: > > > Hi Ivan > > > > if by conflict we mean arguing and fighting it is definitely should be > > avoided, it never helps the community. > > > > But if we mean different opinions on details (variable namings, method > > structure, etc), such different views are unavoidable and I find it is > > perfectly ok that people with different background have different views. > > The paramount thing here if we can solve such conflicts with a positive > > outcome for all community and for the codebase. > > > > The good friend of mine reminded me some time ago that we all have a > common > > goal here: make the community bigger and this project better. If we > always > > remember that we are connected by a common interest but we admit each > > contributor may have different preferences in coding and probably > different > > opinion. We may build up consensus sharing our arguments if it is really > > needed, or these different opinions/priorities/preferences may co-exist. > > > > In a particular case, if reviewer's concerns are not major, another > > reviewer can agree with your proposal. So it should be always considered > > case-by-case, there is no silver bullet here. > > > > Sincerely, > > Dmitriy Pavlov > > > > вт, 23 окт. 2018 г., 11:32 Maxim Muzafarov <[hidden email]>: > > > > > Igniters, > > > > > > I think it's easy to disable the code style abbreviation plugin option > by > > > switching off > > > the checkbox on - File | Settings | Inspections | Apache Ignite | > > Incorrect > > > Java abbreviation usage. > > > > > > +1 to make abbreviation not mandatory, but I'd like to keep it for > common > > > variable names like `context = ctx`. > > > > > > On Mon, 22 Oct 2018 at 14:05 Павлухин Иван <[hidden email]> > wrote: > > > > > > > Hi all, > > > > > > > > I also think that abbreviations should not be mandatory (point 3). > > > > But what I am worrying about is a conflict resolution between a patch > > > > submitter and a reviewer. > > > > How to come to an agreement when one side is strictly for and another > > > side > > > > is strictly against > > > > using abbreviations in some concrete case? > > > > > > > > вс, 21 окт. 2018 г. в 11:34, Dmitriy Pavlov <[hidden email]>: > > > > > > > > > +1 for proposal 3. > > > > > > > > > > 1. I'm not sure we need to revisit all abbreviations as a lot of > > people > > > > get > > > > > used to it. > > > > > 2. I'm not sure multiword is always need to be fully named, > sometimes > > > it > > > > > may be ok to abbreviate. > > > > > 3. But I agree with abbreviations should not be mandatory. > > > > > > > > > > Abbreviated and short names like i,j,cp and etc. are good for > simple > > > > > methods and code blocks; for a fast demonstration of some idea, but > > for > > > > > complex enterprise level software it can hide meaning instead of > > > clearly > > > > > showing it. > > > > > > > > > > As a next step, I would like to propose to contribute an option to > > > > disable > > > > > abbreviation requirements for some cases in ignite-abbrev-plugin. > > > > > > > > > > сб, 20 окт. 2018 г. в 10:47, Zhenya <[hidden email]>: > > > > > > > > > > > +1 for all proposals. > > > > > > > > > > > > > > > > > > > > > > > -- > > > > Best regards, > > > > Ivan Pavlukhin > > > > > > > -- > > > -- > > > Maxim Muzafarov > > > > > > |
Guys, I am sorry I missed this discussion. Apparently, abbreviations use is
far from being the biggest problem in the project. I think everyone agrees here. I vote for leaving abbreviations mandatory, and would be strongly against making them optional since we will endup in situation when different lines of the same method or class will contain abbreviated and non-abbreviated variables, fields and parameters names. This will look ugly. I think nobody thought about source files that are several thousands lines long. Undo abbreviations throughout the entire project is hard work, pretty stupid to do on such huge code base and I am sure will introduce problems and failures on TeamCity. Instead I want to suggest the following: 1. Abbreviations stay mandatory. Making them optional does not make any sense. 2. List of abbreviations should be shortened to up to 20 items and we should leave only those which are common sense. 3. Contributor may also choose to use full words in complex variable names if there is a mix of abbreviated and non-abbreviated words if this helps with readability. I will suggest shorter abbreviations list today or tomorrow and let you know in this thread. Thanks! --Yakov |
Igniters,
I have shortened the list of abbreviation rules and edited our wiki page - https://cwiki.apache.org/confluence/display/IGNITE/Abbreviation+Rules. Thanks to Vladimir Ozerov and Alexey Goncharuk for their useful feedback. My idea was to leave only "common sense" abbreviations and those that are Ignite domain specific. I would also suggest that we treat names mentioned in the table on the page as names that are required to be abbreviated. Please take this into account when conducting code reviews. Thanks! --Yakov |
Free forum by Nabble | Edit this page |