DEV Community

loading...

IF code is commented properly THEN readability is good and ELSE is a useful construct.

brandiware profile image brandiware ・1 min read

Here's my opinion on the numerous attempts to improve code readability by dropping useful language constructs such as ELSE.

Readability IS a sign of code quality - for sure. And it boosts the value of software for quite obvious reasons.

HOWEVER, that is NOT achieved effectively enough by dropping useful elements of the coding language. You can't assert "never use a knive!" simply because MISUSE of knives is dangerous and can be BLOODY.

INSTEAD, consider focussing on MORE and proper COMMENTING (surely you can comment your code even better than in the example below):

// Process the passed argument, ... the result of the ... calculation ... , ... if it IS useful
if myVariable != nil {
//DoSomeUsefulStuff(myVariable)
}

Now judge by yourself how well the else part reads if commented (do provide logical context of the preceeding IF logic)

// Drop out of the function / procedure if the passed argument, ... the result of the ... calculation ... , ... is NOT useful
} else {
return “”
}

My personal bottom line on code readability: do COMMENT amply;

Discussion (2)

pic
Editor guide
Collapse
codedraken profile image
CodeDraken

There's a quote, something like:

"The use of comments is to compensate for our failure to express ourselves in code"

if statements can be cleaned up and made readable by simply using a function in the condition part and in the body.

Example:

// functions
if userExists(myVariable) {
  updateUser(...)
} else {
  createUser(...)
}

// Object-Oriented
if user.isAdmin() {...}

// temporary variables
isUser = myVariable instanceof User
if isUser {...}
Enter fullscreen mode Exit fullscreen mode

A problem with comments is that they clutter the code and slow down reading time and are often forgotten about when updating code. Comments that lie are the last thing you want.

I'm not saying comments shouldn't be used, but they should be used sparingly and only for providing clarification or the intent of some code. It should not just rephrase what the code already says.

And obviously, there are useful tools that use comments i.e. docs, TODOs, etc

Collapse
capjackarrow profile image
capjackarrow

I’m all for comments in the code. After two years in the industry it seems that comments are looked down upon somewhat, for the reason that the code should be written well enough for comments to be unnecessary.

I think that is true for some constructs, like service integrations. They have been patterned and documented so much that there is hopefully enough support to write the code clearly.

However, for constructs that are difficult to design well, or for newer developers, comments are really helpful to support the code, so fresh eyes can understand quickly.

In the end, there are always times when one must write ugly code, so there are always times for comments, such as a page-long script with comments as subtitles.

What do you think?