doc: recommend using port 0 instead of common.PORT

In the 'writing_tests' guide it is recommended to use common.PORT
instead of an arbitrary value, but the recommendation is to use
port 0 instead and the docs should reflect that.

PR-URL: https://github.com/nodejs/node/pull/8694
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Ilkka Myller <ilkka.myller@nodefield.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>

doc/guides/writing_tests.md

@@ -31,9 +31,9 @@ Let's analyze this very basic test from the Node.js test suite:
 6  const server = http.createServer(common.mustCall((req, res) => {
 7    res.end('ok');
 8  }));
-9  server.listen(common.PORT, () => {
+9  server.listen(0, () => {
 10   http.get({
-11     port: common.PORT,
+11     port: server.address().port,
 12     headers: {'Test': 'Düsseldorf'}
 13   }, common.mustCall((res) => {
 14     assert.equal(res.statusCode, 200);
@@ -78,10 +78,11 @@ This is the body of the test. This test is quite simple, it just tests that an
 HTTP server accepts `non-ASCII` characters in the headers of an incoming
 request. Interesting things to notice:
 
-- The use of `common.PORT` as the listening port. Always use `common.PORT`
+- If the test doesn't depend on a specific port number then always use 0 instead
-  instead of using an arbitrary value, as it allows to run tests in parallel
+  of an arbitrary value, as it allows tests to be run in parallel safely, as the
-  safely, as they are not trying to reuse the same port another test is already
+  operating system will assign a random port. If the test requires a specific
-  using.
+  port, for example if the test checks that assigning a specific port works as
+  expected, then it is ok to assign a specific port number.
 - The use of `common.mustCall` to check that some callbacks/listeners are
   called.
 - The HTTP server is closed once all the checks have run. This way, the test can
@@ -131,7 +132,7 @@ process.on('exit', function() {
 var server = http.createServer(function(req, res) {
   request++;
   res.end();
-}).listen(common.PORT, function() {
+}).listen(0, function() {
   var options = {
     agent: null,
     port: this.address().port
@@ -154,7 +155,7 @@ var http = require('http');
 
 var server = http.createServer(common.mustCall(function(req, res) {
   res.end();
-})).listen(common.PORT, function() {
+})).listen(0, function() {
   var options = {
     agent: null,
     port: this.address().port