From f18f9c4095595c6173783452779f97e7f93599f1 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Sun, 27 Dec 2020 11:50:11 +0100 Subject: [PATCH] man-pages.7: Add some notes on comments in example code Signed-off-by: Michael Kerrisk --- man7/man-pages.7 | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/man7/man-pages.7 b/man7/man-pages.7 index 504de2d80..7cf60d22a 100644 --- a/man7/man-pages.7 +++ b/man7/man-pages.7 @@ -949,7 +949,15 @@ Example programs should ideally be short though in some cases longer programs may be necessary to properly illustrate the use of an API. .IP * -Expressive code and useful comments are appreciated. +Expressive code is appreciated. +.IP * +Comments should included where helpful. +Complete sentences in free-standing comments should be +terminated by a period. +Periods should generally be omitted in "tag" comments +(i.e., comments that are placed on the same line of code); +such comments are in any case typically brief phrases +rather than complete sentences. .IP * Example programs should do error checking after system calls and library function calls.