On 10/13/2014 05:23 PM, Sean Silva       wrote:
    
           
        
          On Mon, Oct 13, 2014 at 5:09 PM, Jim             Grosbach <grosbach@apple.com>             wrote:
                           
                
                  
                    
                                               
On Oct 13, 2014, at 4:31 PM, Chandler                           Carruth <chandlerc@google.com>                           wrote:
                        
                        
                                                       
                              On Mon, Oct 13,                                 2014 at 4:14 PM, Chandler Carruth <chandlerc@google.com>                                 wrote:
                                                                                                            
1. Initialisms. It's common                                         in Clang code (also in LLVM?) to                                         use initialisms as variable                                         names. This doesn't really seem                                         to work for names that start                                         with a lower case letter.
                                                                         

                                    
                                                                     
I think wee at least need a good                                     answer to this.
                                                               
                              
                              As I really suspect this is the most                               important point to address, let me make an                               attempt:
                            
                            
                            Variable names are                               *either* initialisms, written as all caps,                               or terms written in lower case and                               separated by underscores. For the purposes                               of variable naming "terms" can include                               words but also extremely common and                               recognizable abbreviations within LLVM                               such as "rhs", "lhs", or "gep". These                               types of terms should not be written as                               initialisms but as words. For example, you                               might write "LE" or "lhs_expr" for the                               Left-hand Expression, but not "LHSE" or                               "LHS_expr".
                            
                                                         While I'm trying to                               avoid it, this has the advantage of                               leaving a large number of initialisms in                               the existing code base as "stylish".                             
                                                         
                                                         I'm not really                               happy with this rule, but it is the least                               disruptive and most consistent I can come                               up with. I would also be happy encouraging                               people to not use initialisms excessively                               or if confusing. I think the current                               codebase uses them more than is helpful.                                                                                                  

                      
                                                          
This makes sense to me. I think it strikes a good                     balance between updating our conventions to be                     better and also reflecting common in-practice usage                     patterns.
                                                         

            
            
This convention sounds like it would cause people to               have to be constantly asking themselves "is this common               enough to be an initialism-as-word or not?". The thing               that started this conversation was someone complaining               about going between codebases that they weren't sure               whether to capitalize; now that person will have to get a               feel for the local initialism-as-word's, which is a much               greater burden than just the naming convention.               

              
              
-- Sean Silva
            
                                    In practice, you have to set such a threshold somewhere.  Otherwise,     you end up not being able to use terms like SSA, or Phi without an     explanation.  My view is that common initialisms like lhs, gep, and     dt should be accepted.  If you haven't spent enough time in the code     to recognize them, you probably shouldn't have commit rights     anyways.  

FWIW I don't know what dt means here (dominator tree? debug type?)

Remember, one of the gripes about the current convention is that it is a turn-off for people new to LLVM development (which often means not that knowledgable about compilers). Thus "you probably shouldn't have commit rights anyways" is an extremely counter-productive way to think about this.

    
    I am in favor of keeping that list of initialisms small.  Adding a     new one (either for an area, or the project as a whole) should     trigger discussion outside of a single review thread.

This sounds like a strict increase in the amount of thinking about pointless things that I have to do when coming up with a variable name. Currently I only have to think about where my current file is. Now you are suggesting that I should have to think about whether something is common enough or not (which is actually real "AI Complete" thinking)?

-- Sean Silva
 

    
    Philip
                               
            
 
                                            
                    

                    
                    
                      FWIW, I think that having                         different naming conventions for data members                         and local variables has become essentially                         untenable with lambdas and capture.                       
                    
                                     
Can you elaborate a bit more on this? Maybe an                     example or two.
                  

                  
                  
I’m very supportive of the general direction of                     all of this. Glad to see the general consensus                     developing.
                                         

                      
                      
-Jim
                      

                      
                    
                             
              _______________________________________________
              LLVM Developers mailing list
              LLVMdev@cs.uiuc.edu                       http://llvm.cs.uiuc.edu
              http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
              
                                  
                      
      
      
      
_______________________________________________
LLVM Developers mailing list
LLVMdev@cs.uiuc.edu         http://llvm.cs.uiuc.edu
http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
         
  ">

(original) (raw)



On Mon, Oct 13, 2014 at 5:46 PM, Philip Reames <listmail@philipreames.com> wrote:

On 10/13/2014 05:23 PM, Sean Silva wrote:


On Mon, Oct 13, 2014 at 5:09 PM, Jim Grosbach <grosbach@apple.com> wrote:

On Oct 13, 2014, at 4:31 PM, Chandler Carruth <chandlerc@google.com> wrote:


On Mon, Oct 13, 2014 at 4:14 PM, Chandler Carruth <chandlerc@google.com> wrote:
1\. Initialisms. It's common in Clang code (also in LLVM?) to use initialisms as variable names. This doesn't really seem to work for names that start with a lower case letter.
I think wee at least need a good answer to this.

As I really suspect this is the most important point to address, let me make an attempt:

Variable names are \*either\* initialisms, written as all caps, or terms written in lower case and separated by underscores. For the purposes of variable naming "terms" can include words but also extremely common and recognizable abbreviations within LLVM such as "rhs", "lhs", or "gep". These types of terms should not be written as initialisms but as words. For example, you might write "LE" or "lhs\_expr" for the Left-hand Expression, but not "LHSE" or "LHS\_expr".

While I'm trying to avoid it, this has the advantage of leaving a large number of initialisms in the existing code base as "stylish".


I'm not really happy with this rule, but it is the least disruptive and most consistent I can come up with. I would also be happy encouraging people to not use initialisms excessively or if confusing. I think the current codebase uses them more than is helpful.

This makes sense to me. I think it strikes a good balance between updating our conventions to be better and also reflecting common in-practice usage patterns.

This convention sounds like it would cause people to have to be constantly asking themselves "is this common enough to be an initialism-as-word or not?". The thing that started this conversation was someone complaining about going between codebases that they weren't sure whether to capitalize; now that person will have to get a feel for the local initialism-as-word's, which is a much greater burden than just the naming convention.

-- Sean Silva
 In practice, you have to set such a threshold somewhere. Otherwise, you end up not being able to use terms like SSA, or Phi without an explanation. My view is that common initialisms like lhs, gep, and dt should be accepted. If you haven't spent enough time in the code to recognize them, you probably shouldn't have commit rights anyways.

FWIW I don't know what dt means here (dominator tree? debug type?)

Remember, one of the gripes about the current convention is that it is a turn-off for people new to LLVM development (which often means not that knowledgable about compilers). Thus "you probably shouldn't have commit rights anyways" is an extremely counter-productive way to think about this.


I am in favor of keeping that list of initialisms small. Adding a new one (either for an area, or the project as a whole) should trigger discussion outside of a single review thread.

This sounds like a strict increase in the amount of thinking about pointless things that I have to do when coming up with a variable name. Currently I only have to think about where my current file is. Now you are suggesting that I should have to think about whether something is common enough or not (which is actually real "AI Complete" thinking)?

-- Sean Silva


Philip


FWIW, I think that having different naming conventions for data members and local variables has become essentially untenable with lambdas and capture.
Can you elaborate a bit more on this? Maybe an example or two.

I’m very supportive of the general direction of all of this. Glad to see the general consensus developing.

-Jim


\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
LLVM Developers mailing list
LLVMdev@cs.uiuc.edu http://llvm.cs.uiuc.edu
http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev




\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_  
LLVM Developers mailing list  
LLVMdev@cs.uiuc.edu http://llvm.cs.uiuc.edu  
http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev