Какой хороший способ сделать тип множественным числом при написании комментариев?
При написании комментариев, Иногда мне приходится говорить о типе (классе, структуре и т. Д.) Во множественном числе при написании комментариев, например:
/*
* getThings
* Get a list of --> Things <-- from somewhere.
*/
Thing *getThings(void);
Проблема в том, что имя типа является единственным (а именно, Thing ) , но я хочу поговорить о них во множественном числе в комментариях.
Если я говорю Вещи , это предлагает читателю: речь идет о типе под названием Things , что не так. Если я скажу Thing's , это выглядит неловко, потому что это не грамматически правильно (это либо притяжательное, либо «Thing is», а не множественное число). Я мог бы обсудить эту проблему и сказать список предметов Thing
. К чему следует придерживаться при написании множественного числа типов?
2 ответа
Что ж, в зависимости от системы документации, которую вы используете, вы можете заключить имя типа в специальный синтаксис и поместить за ним s . Например:
.NET XML комментарии
Get a list of <see cref="Thing"/>s from somewhere.
doxygen C / C ++ комментарии
Get a list of \link Thing \endlink s from somewhere.
Не уверен на 100% в варианте doxygen, но он должен быть примерно таким.
А если вы не пользуетесь какой-то конкретной системой документации и, следовательно, не имеете специальных комментариев, я бы сделал что-то вроде:
Get a list of [Thing]s from somewhere.
Или вы можете использовать () или {}, в зависимости от предпочтений ...
Я бы использовал 's' в скобках.
/* Get a list of Thing(s) from somewhere */