Writing readable code and not overdoing it with naming

Question

I've been in an argument at work about writing readable code. It was mainly about variable and method names and the idea that comments are worthless if the code is readable enough. I would not like to emphasize only on no specific coding language.

1.) Descriptive vs minimalistic variable and method names Descriptive variable names are easier for a newcommer to understand while minimalistic makes it easier to navigate your code (No screen cluttered with long camelCase names) Lets say i have a method:

• convertOneFormatToAnotherFormat() vs oneFormatToAnother()
• checkIfTypeIsBoolean() vs isBoolean
• rerenderNavigationInNavbar vs refreshNavbar()

What would you say a good rule is?

2.) Using abbrevations for variable naming vs using full names everytime Abbrevations makes your code less cluttered, while full names make it easier to understand. The point of the argument was that i said that some abbrevations are better then fullNames. Lets check the silly examples:

• JSON vs javascriptObjectNotation
• RGB vs redGreenBlue
• VB vs visualBasic

Of couse abbrevations are better.

• conv vs convert
• dev vs developer
• usr vs user

Full names are better here for sure. I would like to ask for oppinions here for some more unclear examples:

• kvp vs keyValuePair
• ddl vs dropDownList

What would you choose here? Also, how would you write a rule for naming with abbrevations?

3.) Comments not needed if code is readable enough There is a standard that says that documentation and comments are not needed if the code is readable enough. And yet i have found that i have made some specific choices in my code and wanted to explain my choices in the comments above.

• Would you say comments in code that explain logic are needed?
• Would you say that comments that only segmentize the code are needed?
• Would you document HTML with comments? (End tags, beginning tags (, )

4.) Short names in short standalone function vs meaningfull names Lets say i have a method that finds returns a number and multiplies it by 2 Is it ok to:

multiplyByTwo(x):
    a = x*2
    return a

or is it a lot better to:

multiplyByTwo(factor):
    result = factor*2
    return result

I know the best way is to be smart about it and use the one that informs the reader and makes his job the easiest possible is the best one, but for teams this is difficult to do since each one has his own style.

Thank you for the response

Answer 1

1.) Descriptive vs minimalistic variable and method names Descriptive variable names are easier for a newcommer to understand while minimalistic makes it easier to navigate your code (No screen cluttered with long camelCase names) Lets say i have a method:

convertOneFormatToAnotherFormat() vs oneFormatToAnother()
checkIfTypeIsBoolean() vs isBoolean
rerenderNavigationInNavbar vs refreshNavbar()

What would you say a good rule is?

At first they should follow naming conventions which (in Java) includes that method names always start with a verb.

Then you example read out a bit foolish because they are (intentionally) generic. But what about this?

convertXmlToJson() 

2.) Using abbrevations for variable naming vs using full names everytime

• JSON vs javascriptObjectNotation
• RGB vs redGreenBlue
• VB vs visualBasic

I'd say using (very) common acronyms is OK.

But

Of couse abbrevations are better.

• conv vs convert
• dev vs developer
• usr vs user

Full names are better here for sure. I would like to ask for oppinions here for some more unclear examples:

• kvp vs keyValuePair
• ddl vs dropDownList

abbreviations are no good at all.

3.) Comments not needed if code is readable enough

Comments comments should explain why the code is like it is. E.g. why you preferred a certain syntax or structure over another, more common (within your codebase)...

Also interfaces usually need comments to help the implementer understanding the contract behind it.

• Would you say comments in code that explain logic are needed?

No

• Would you say that comments that only segmentize the code are needed?

No

• Would you document HTML with comments? (End tags, beginning tags (, )

No (I have Tools with proper highlighting)

4.) Short names in short standalone function vs meaningfull names

Is a special case of the abbreviation issue...

Answer 2

Just like any language meaning is often given by context and history.

for example ddl is a common abbreviation for drop down list in some contexts but not others. If you come from a VB6 background you may use comboBox instead.

The clean coding philosophy would have you get rid of comments entirely, but in my view that is rather narrow minded. It depends on everyone having the same view of 'readablity'. If you have worked with developers who don't speak English or systems with odd terminology you will know that long names don't always explain what the code is doing.

Just as you have discovered with your colleague, what one person find readable another doesn't.

So in general. Yes, avoid myFunc(x) and //adding two to the number but don't go crazy. A combination of comments and longer names will see you though eg

///
///convert incoming JSON data into Data object so that we can blah blah
///
Data ParseJson(string json) {...}