Perhaps it is not news to everyone that there are two hard things in Computer Science . I previously explained why I felt because there is some art in doing it . I will not spend any time here arguing whether naming things is an art or not. programming is not boring Instead, I will just go straight into how to name things properly. All the examples below uses the even though the same principles can be applied to other languages. Julia language Why? To me, it is extremely important to write code that is readable and easy to understand. If I write it properly, my colleagues will be able to read it, support it, and enhance it going forward. If I write it badly, I may even curse at myself in the future. I will not cover naming conventions such as or , as they are fairly well documented and understood. Rather, I will focus more about the semantics. CamelCase snake_case As our journey begins... What are the things that we need to give names to? In Julia, the main things are modules, data types, functions, constants and variables. The very first decision is to choose between using a , a , or an . verb noun adjective This is actually not too difficult. One reasonable approach is to adopt the following convention: Naming modules A good module name typically encompasses a group of concepts and functionalities provided by the module. It needs to be broad enough to cover all functionalities but specific enough to distinguish itself from other modules. For example, I have a module that provides an implementation of a circular linked list. I do not name it as , nor would I name it as , for those are too broad of a concept. CircularList LinkedList List Sometimes you want to think bigger and name the module a little broader than what is currently implemented. I think it is appropriate as long as there is a plan to develop the package further, and it does not cause any confusion for any user of the package. But, it should not miss the mark. Additional guidance can be found at the documentation. Julia package naming guidelines Naming data types Data types are used to represent either abstract concepts (abstract types) or concrete data structures (concrete types). That's why using nouns would be appropriate. In the case that data types represent behavior or traits, it is appropriate to use adjective such as and . Iterable Pretty A general rule of thumb is to come up with names that are not too long. I would say any name that is composed of more than three words is . code smell So, is perfectly fine and even is acceptable but would be too long. ProductCatalog ElectronicProductCatalog ElectronicDepartmentProductCatalog Why is it bad? It is because long names are harder to read and spelling mistake are hard to find, causing headaches during debugging. Naming functions For functions, when should I use verbs? And when should I use nouns? There is no hard-and-fast rule. Based upon my experience, I have developed an intuition to make these kinds of judgment. Let me illustrate my thought process with an example. How a noun looks better than a verb... Let's say I am working on an e-commerce site and I have a data type. I want to define a function that determines the price of the product based upon the current market condition. I can think of two names - and . Product current_price calculate_price Now, consider the code below: product products current_price(product) price_range add(search_result, product) for in if in end end Does it look better or worse if I choose instead? I bet it would look worse! calculate_price The reason why looks better is that it's easier to read. I can read the code as But, I cannot read the code as " current_price "if current price of the product is in the price range..." if calculate price of the product is in the price range...". Get it? When I use , I'm emphasizing the thing that is being returned from the function rather than how it does its job. current_price At this point, one may argue that the readability issue can be resolved with a temporary variable. Let's assign the result of the function call to a variable: price product products price = calculate_price(product) price price_range add(search_result, product) for in if in end end Sure, that could work but obviously it limits the way you write code, so I can't say it's optimal. How a verb looks better than a noun... Next, let's consider the case that I need a new function that find the best price of the product using several different pricing algorithms. So, the pricing function needs to take an algorithm argument. Let's write the function and its corresponding doc string above: current_price(product::Product, algorithm::Algorithm) "Return the current price of the product calculated using the specified algorithm." At this point, it starts to feel just a little more awkward to read. Let's try to use a verb: calculate_price(product::Product, algorithm::Algorithm) "Calculate the price of the product using the specified algorithm." Using a verb makes it more natural when you need to emphasize the action being taken to get the job done. In this example, the use of calculate goes together with the argument algorithm quite well. So, my point is, what do you want to emphasize when calling the function. Is it the thing that it returns, or the process that it goes through? You should be able to make a better decision when you can answer the above question. Naming Constants/Variables I believe the best code should be readable. More often than not, I have heard from other programming experts about using meaningful words for all variables in the code. I can agree to that most of the time, until the verbosity kicks in and kills readability. Religiously. I can think of two examples where it makes sense to use terse names. Doing Math The first case is code that performs heavy-lifting mathematical calculations. It is usually more natural to use math symbols than English words. Julia has and this is an area where it shines. Here's an example from my package: full support of Unicode BoxCoxTrans.jl transform(𝐱, λ; α = , scaled = , kwargs...) α != 𝐱 .+= α any(𝐱 .<= ) && throw( ( )) scaled gm = geomean(𝐱) @. λ ≈ ? gm * log(𝐱) : (𝐱 ^ λ - ) / (λ * gm ^ (λ - )) @. λ ≈ ? log(𝐱) : (𝐱 ^ λ - ) / λ function 0 false if 0 end 0 DomainError "Data must be positive and ideally greater than 1. You may specify α argument(shift). " if 0 1 1 else 0 1 end end At current state, the code looks fairly clean and maybe even resembles the formula found in a math research paper. By contrast, it would look very ugly if I have to replace all symbols with names like , , and . alpha lambda time_series Indexing arrays The second case relates to the argument about naming indexing variables such as . I generally oppose this idea. For simple code, it does not matter. For something more complex, it goes against you and hurts readability. index Consider this code that I found from the package: LinearAlgebra rcswap!(i:: , j:: , X:: {<: }) k = :size(X, ) X[k,i], X[k,j] = X[k,j], X[k,i] k = :size(X, ) X[i,k], X[j,k] = X[j,k], X[i,k] ## Swap rows i and j and columns i and j in X function Integer Integer StridedMatrix Number for 1 1 end for 1 2 end end Let's just do an exercise and see how it looks if we replace those short variable names with the more meaningful and longer version: rcswap!(index1:: , index2:: , matrix:: {<: }) position = :size(matrix, ) matrix[position,index1], matrix[position,index2] = matrix[position,index2], matrix[position,index1] position = :size(matrix, ) matrix[index1,position], matrix[index2,position] = matrix[index2,position], matrix[index1,position] function Integer Integer StridedMatrix Number for 1 1 end for 1 2 end end If the purpose of using longer variable names is to improve readability, then this is doing more harm than good. By contrast, using single-letter variable names is not too bad. In fact, it is quite common that single-letter variable names are used for indexing arrays in any programming language tutorials (e.g. , , , and ). python java javascript rust In addition, whenever I read code, my brain already translates them to read like index. Really, there is no difference between , , or . i j k index They all look the same to me. Wrapping up... Is naming things actually difficult? Definitely, maybe. You may think that I always name things properly? Wrong! I am definitely not perfect. Having written a book and a couple of blog posts, I have come to realize that writing code is no difference from other types of writing in general. You must keep revising (refactoring) to make it right. I do believe that practice makes perfect. I would encourage you to ask someone else to read your code and give you feedback. P.S. For more tips in writing good code in Julia, consider picking up my book Hands-on Design Patterns and Best Practices with Julia .
