Во-первых, мне известен этот вопрос: Существуют ли стандартные форматы комментариев в коде?
Но он не ответил на мой.Всякий раз, когда я пишу код, я всегда стараюсь выработать привычку к тому, чтобы все комментарии были согласованы, но именно здесь я иногда не решаюсь относительно соглашения о формате кода.Тем более, что я хочу, чтобы мой код имел ширину около 80 строк.
Излишне говорить, что формат кода должен быть следующим:
- Легко читаемое
- Легкоизменить
И в разных частях вашего кода могут быть разные форматы комментариев, поэтому важно убедиться, что они остаются согласованными и читаемыми.
Вот несколько примеров:
Однострочный
// simple comment in lowercase
do_something();
// longer comment in lowercase. but now it doesn't seem like a proper sentence.
do_something();
// Longer comment in sentence case. But should we use sentence case for short comments too?
do_something();
// Like this one?
do_something_else(); // Or even this one.
Многолинейный
// This code is very detailed and so I must continue further.
// Every time you start a new line you need to ensure you add //.
// If you finish your comment and forget to add something, you're screwed.
// You'll have to add your something and then make sure all the lines are 80 characters or less,
// and if they aren't you need to restructure all the lines below it.
/* This is better but you need to make sure it's properly indented each line.
Although you have to worry about those comment delimiters getting in the way.
At least it's compact. */
/* This comment seems better.
No need to worry about that last delimiter being inside your comment block.
*/
/*
Or maybe this is better?
At least it looks clean.
*/
/* GOOD FOR FUNCTION DEFINITIONS
Or maybe this is even better?
Who knows?
*/