doc: note that tests should include a description

Update the Writing Tests guide to specify that tests should include a
brief description of what they are designed to test.

PR-URL: #9415

Reviewed-By: Santiago Gimeno <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Sakthipriyan Vairamani <[email protected]>oc

Author: gibfahn

doc/guides/writing_tests.md

@@ -23,23 +23,27 @@ Tests can be added for multiple reasons:
 Let's analyze this very basic test from the Node.js test suite:
 
 ```javascript
-1  'use strict'; 
-2  const common = require('../common');
-3  const http = require('http');
-4  const assert = require('assert');
-5
-6  const server = http.createServer(common.mustCall((req, res) => {
-7    res.end('ok');
-8  }));
-9  server.listen(0, () => {
-10   http.get({
-11     port: server.address().port,
-12     headers: {'Test': 'Düsseldorf'}
-13   }, common.mustCall((res) => {
-14     assert.equal(res.statusCode, 200);
-15     server.close();
-16   }));
-17 });
+1   'use strict';
+2   const common = require('../common');
+3
+4   // This test ensures that the http-parser can handle UTF-8 characters
+5   // in the http header.
+6
+7   const http = require('http');
+8   const assert = require('assert');
+9
+10  const server = http.createServer(common.mustCall((req, res) => {
+11    res.end('ok');
+12  }));
+13  server.listen(0, () => {
+14   http.get({
+15     port: server.address().port,
+16     headers: {'Test': 'Düsseldorf'}
+17   }, common.mustCall((res) => {
+18     assert.strictEqual(res.statusCode, 200);
+19     server.close();
+20   }));
+21 });
 ```
 
 **Lines 1-2**
@@ -60,7 +64,18 @@ require('../common');
 
 Why? It checks for leaks of globals.
 
-**Lines 3-4**
+**Lines 4-5**
+
+```javascript
+// This test ensures that the http-parser can handle UTF-8 characters
+// in the http header.
+```
+
+A test should start with a comment containing a brief description of what it is
+designed to test.
+
+
+**Lines 7-8**
 
 ```javascript
 const http = require('http');
@@ -72,7 +87,7 @@ modules should only include core modules.
 The `assert` module is used by most of the tests to check that the assumptions
 for the test are met.
 
-**Lines 6-17**
+**Lines 10-21**
 
 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