“The proper use of comments is to compensate for the failure to express yourself in code.”
Robert Cecil Martin, Clean Code: A Handbook of Agile Software Craftsmanship
IMHO Robert Martin is arrogant. Everybody wants self-explanatory code but usually, it is not possible (unless the code is trivial), so it’s easy to preach something that it is virtually impossible to achieve.
Anyways, about commenting, some languages allow “block of codes.” This block of code is understandable by the IDE (and it is one of the reasons why devs mustn’t use notepad instead of a proper IDE).
For example, it is part of my code:
/**
* DaoOne constructor. It doesn't connect to the database.
* @param string $server server ip. Ex. 127.0.0.1
* @param string $user Ex. root
* @param string $pwd Ex. 12345
* @param string $db Ex. mybase
* @param string $logFile Optional log file. Example c:\\temp\log.log
* @param string $charset Example utf8mb4
* @param int $nodeId It is the id of the node (server). It is used for sequence. Up to 4096
* @see DaoOne::connect()
*/
public function __construct($server, $user, $pwd, $db, $logFile = "",$charset='',$nodeId=1)
{So, in case of doubt, the IDE will help to identify every argument, and what it does, so the users don’t need to peek at the documentation, documentation that still must exist.
So, let’s say that I am using the constructor and I don’t know the arguments. In this case, PHPStorm will show the documentation:
