-3

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

closed as primarily opinion-based by gnat, Jörg W Mittag, amon, Robbie Dee, James McLeod Dec 5 '17 at 14:14

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

  • 3
  • 2
    How can a response to this possibly be anything other than subjective opinion? – mickeyf Dec 5 '17 at 13:16
  • 3
  • 1
    1 or 2 ch nm is ok to rd no? – user251748 Dec 5 '17 at 15:55
  • Just in my opinion, I've never encountered implementations written by someone else where the comments or identifiers helped that much in understanding what the code did. Either I was familiar with the design pattern or algorithm being used, at which point anything within reason is easy enough for me to immediately recognize and understand, or I wasn't at which point even very nicely commented code wasn't going to be so effective in teaching me new algorithms. Interfaces are a different case. Comments and clear names can really help there as long as they aren't too verbose... – user204677 Dec 5 '17 at 23:54
1

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) {...}
  • 1
    While this may be true for new code: what about evolving code? Comments like this tend not to get updated as the codes behavior/responsibility changes. Reasons may be time restrictions or careless developers.... You might say that is is easy to find out, but what purpose does a comment serve if I have to check with the code if it is still valid? – Timothy Truckle Dec 5 '17 at 13:17
  • The same argument could apply to the name. But! the idea with this kind of comment is you describe what the intention of the function is. what it SHOULD do, not what it does. This is usually more constant over the life time of an app and too long to condense to a function name. – Ewan Dec 5 '17 at 13:19
  • Adding comments for terse code just shifts the problem... – Robbie Dee Dec 5 '17 at 13:20
  • but adding comments to verbose code gives valuable information – Ewan Dec 5 '17 at 13:21
  • "The same argument could apply to the name." which makes two lies against one truth. Much better... "But! the idea with this kind of comment is you describe what the intention of the function is. what it SHOULD do" which is also true for the functions name! – Timothy Truckle Dec 5 '17 at 13:21
0

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

Not the answer you're looking for? Browse other questions tagged or ask your own question.