-1

Debugging old code in dynamically typed languages like Python, Ruby, JavaScript, etc. is often a struggle. For example, below Ruby function extracts only the key:val pairs from the result (hash) if a key is present in filters (array).

def filter(result, filters)
end

At glance there is no way of telling the data types for result and filters. Also we don't know if the result hash is using symbols or strings keys. We also don't know the data type expected by the filters elements.

My question is, how can I improve my code readability and what is the general best practice? Two things that come to mind are:

  1. Comments - I generally avoid too many comments and would prefer making the code more descriptive. Also adding comments for each variables defined inside the function may populate the code with too many comments.

    # result: hash | filters: array (strings)
def filter(result, filters)
end

  2. Variable Naming - Adding the data type in variable name. I'm not sure if this is good practice. e.g.

    def filter(result_hash, filters_array)
end

EDIT: I thought there was a standard but, I learned that this is an opinion-based question. It was good to learn about the different options available!

Dante
  • 537
  • 2
  • 4
  • 18
  • 1
    This is too broad a question because there are different answers for different languages. Python solves this problem very cleanly with type annotations. – Samwise Jun 01 '22 at 19:21
  • @Samwise I wasn't aware of the concept of "type annotation" so this is a good start. I will look this up for different languages. – Dante Jun 01 '22 at 19:23
  • 1
    You might like [Hungarian notation](https://en.wikipedia.org/wiki/Hungarian_notation) – Clive Jun 01 '22 at 19:28
  • 2
    Please note the following in regards to ruby: 1) Comments: almost all of the documentation you read for ruby libraries is generated from code comments (including the core language documents). This is done using documentation parsers like RDoc or Yard; 2) Variable Naming: ruby (and python from my understanding) is what is affectionately refered to as a "duck typing" language. They do not rely on the object type but rather the messages that such an object can receive. For this reason including the "type" in the name seems counter productive in my opinion. – engineersmnky Jun 01 '22 at 19:46
  • @Clive Very interesting naming convention – Dante Jun 02 '22 at 06:57

1 Answers1

1

Both of your methods are suboptimal, although the first one is more maintainable and more readable.

  1. The variable names are too generic.

    # result: hash | filters: array (strings)
def filter(result, filters)
end

  2. Variable names encode the data type, which is usually (a) not needed in practice, (b) not very readable, and (c) can change with time, requiring a variable names change.

    def filter(result_hash, filters_array)
end

I recommend a naming convention that is more specific and does not depend on the type of the variable. Use plurals for arrays/lists, singular for scalars, and also singular for hashes/dictionaries. For example:

def clean_patient_chart(patient_chart, filters)
    return clean_patient_chart
end
Timur Shtatland
  • 12,024
  • 2
  • 30
  • 47