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:
- 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