As per Drupal 7 and 8 beta, instructions in default.settings.php need to be more user friendly.
A new user or novice will not know what must be uncommented in that file to configure the database connection. This is a real issue: not only is it critical for installation to succeed, it is a turn-off and intimidating.
The configuration options below the database part are more clear, but for the first basic part to set-up the database, more user friendly phrases need to be added, such as "Uncomment the following lines (except @code and @endcode) and replace the words databasename username and password with those that apply...".
Here is another example of what cannot be understood :
* WARNING: These defaults are designed for database portability. Changing them
* may cause unexpected behavior, including potential data loss.
*
* @see DatabaseConnection_mysql::__construct
* @see DatabaseConnection_pgsql::__construct
* @see DatabaseConnection_sqlite::__construct
In the above code, what are we to understand, use or uncomment and why ? @see implies we can read more somewhere, but I fail to grasp what this is though I have been using Drupal since Drupal 4.
A positive example is the .htaccess file, which clearly uses phrases like "You may uncomment the following line if...".
As Drupal 8 must be user friendly, and as even an experienced Drupal user like myself had to search the web to feel more at ease with default.settings.php (as of current Drupal 7 and Drupal 8), I think this task is fundamental ("The major priority is used for issues that are not critical, but that do have significant impact...").