DEV Community

Discussion on: Most effective and simplest way to write readable code.

Collapse
 
alphawong profile image
Alpha • Edited

Disagree, code is for human to read. A good code comment will enable following developer easy to pickup. For instance

// php5
function SetUserBalance($balance){
  return [
    'balance' => $balance
  ]
}

// php7
// Should I use float or string?
function SetUserBalance(float $balance):array

function SetUserBalance(string $balance):array

A meaning comment always help developer to maintain the code without misunderstanding.

If we can make a comment as follow

// php5
/**
SetUserBalance will set the balance for the user
@param float $balance must be string in order to avoid possible lost
@return array about the current user information.
**/
function SetUserBalance($balance){
  return [
    'balance' => $balance
  ]
}

See also github.com/Microsoft/vscode/blob/m...